PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / basic / pbclone.exe / PBCLONE.MAN < prev next >

Wrap

Text File | 1993-01-12 | 377.4 KB | 11,780 lines

PBClone 2.1 (c) 1990-1993 Thomas G. Hanlin III Name : AddMatI (Add Matrix Integer) Class : Array management Level : Any This routine adds an integer to as many elements of an integer array as you like, starting at a specified place in the array. It can also be used to subtract (just specify a negative value). If there was a numeric overflow at any point in the operation, an error code will be returned. AddMatI DSeg%, DOfs%, Elements%, Value%, ErrCode% DSeg% segment of the first array element to add DOfs% offset of the first array element to add Elements% number of array elements to which to add Value% value to add to each array element ------- ErrCode% error code: 0 if no error Name : AddMatL (Add Matrix Long integer) Class : Array management Level : Any This routine adds a long integer to as many elements of an long integer array as you like, starting at a specified place in the array. It can also be used to subtract (just specify a negative value). If there was a numeric overflow at any point in the operation, an error code will be returned. AddMatL DSeg%, DOfs%, Elements%, Value&, ErrCode% DSeg% segment of the first array element to add DOfs% offset of the first array element to add Elements% number of array elements to which to add Value& value to add to each array element ------- ErrCode% error code: 0 if no error Name : AllExtMem& (All Extended Memory) Class : Equipment Level : Clone (AT) This routine returns the amount of extended memory installed in the system, as reported by the power-on self-test (POST) routine at boot time. This does not tell you how much extended memory is actually available, since extended memory may be carved up by users of BIOS-level extended memory or XMS memory, converted to expanded memory, etc. It only tells you the amount of physical extended memory that is installed. Do not use this routine on PC/XT machines. It is only for AT-class computers. TotalKb& = AllExtMem& ------- TotalKb& kilobytes of extended memory installed Name : AltKey (Alt Key) Class : Input Level : Any This routine works in conjunction with a key input routine, such as INKEY$ or the CheckKey and GetKey routines. Given the ASCII code and scan code of a key, AltKey returns the associated key letter, if any. For instance, it returns "A" if you pass it ASCII code 0 and scan code 30, because those codes represent Alt-A. AltKey ASCIICode%, ScanCode%, Ky$ ASCIICode% ASCII code of the key ScanCode% scan code of the key ------- Ky$ associated key letter ("" if none) Name : AndSt (AND String) Class : String Level : Any This routine ANDs each byte in one string with the corresponding byte in a second string. The strings must be the same length. AndSt St1$, St2$ St1$ string to AND St2$ string to AND with ------- St1$ result Name : Any2Dec (Any to Decimal) Class : Numeric Level : Any This routine converts a number in any base to a normal (base 10) integer. It works like the &H and &O prefixes in BASIC, but rather than working only in hexadecimal (base 16) and octal (base 8), it can be used for binary, octal, or almost anything else. The base may range from 2-35. The input number may be in either signed or unsigned integer form, and will be converted to a signed integer. For example, the base 16 (hexadecimal) number FFFF would be converted to -1, as would the base 10 (decimal) number 65535. This may not seem to make sense if you're not familiar with the internal format for integers, but is the standard approach to converting unsigned numbers (0-65535) to signed numbers (-32768 to 32767). BASIC always uses signed integers, so the numbers will always be what you expect so long as they are kept in the range -32768 to 32767. They "wrap around" for 32768 to 65535. The most common bases used on computers are base 2 (binary), base 8 (octal), base 10 (decimal), and base 16 (hexadecimal). Any2Dec Number$, NrBase%, DecNr%, ErrCode% Number$ any-base number to convert to an integer NrBase% number base to convert from ------- DecNr% resulting integer ErrCode% error code: 0 if no error Name : AscI% (ASC Integer) Class : String Level : Any This is a replacement for the ASC function provided by BASIC. It is smaller than ASC, however, and also somewhat faster. Unlike BASIC or ProBas, the PBClone AscI function returns -1 as an error condition if you try to use it on a null string. This convention owes its origin to the similar routine in Crescent's libraries. See also AscM%, which returns the ASCII code of a character at a specific location within a string. Value% = AscI%(St$) St$ string for which to return ASCII code ------- Value% code of the first string char or -1 if null string Name : AscM% (ASC MID$) Class : String Level : Any This function works like a combination of the BASIC functions ASC and MID$. It returns the ASCII code of a character at a specified position in a string. If the specified position is outside the string, -1 will be returned. See also AscI%, which returns the ASCII code of the character at the beginning of a string. Value% = AscM%(St$, Posn%) St$ string to examine Posn% character position to examine ------- Value% code of the specified character or -1 if error Name : BarMenu (Bar Menu) Class : Input Level : Clone This is a bar menu routine. It allows the user to select one of a list of items given on a single menu row or "bar". The current item is highlighted in your choice of colors; user selection can be done either by moving this highlight and pressing return or by entering the letter associated with the desired item. Only text mode is supported. The highlight may be moved with the left and right arrow keys, tab and backtab, or space and backspace. Selection is done with <CR>, the enter key. The letter used to select an item is the first character of the item that is not lowercase or a space. If the item is all lowercase, the first character of the item will be used. For example, suppose you want the user to select one of "list" or "log". By passing the options to BarMenu as "List" and "lOg", you allow the user to press "L" for "List" and "O" for "lOg". The user's choice will be returned to you as a number, with the first choice being numbered 1. If <ESC> was pressed, 0 will be returned. BarMenu Pick$(), Row%, LCol%, RCol%, VAttr%, HiAttr%, Prompt$ Pick$() list of items to choose from Row% row on which to display the bar LCol% leftmost column of the bar RCol% rightmost column of the bar (use -1 for autosize) VAttr% bar color/attribute (see CalcAttr) HiAttr% bar highlight color/attribute (see CalcAttr) Prompt$ prompt text (displayed at left side of the bar) ------- Row% # of the chosen item (1-items, or 0 if <ESC>) Name : BarMenuM (Bar Menu with Mouse) Class : Input, Mouse Level : Clone This is a bar menu routine. It functions just like BarMenu, but supports the use of a mouse as well as the keyboard. Make sure the mouse cursor is visible before calling this routine! BarMenuM PickList$(), Row%, LeftCol%, RightCol%, VAttr%, _ HiAttr%, Prompt$, Mouse%, ShowCursor% PickList$() list of items to choose from Row% row on which to display the bar LeftCol% leftmost column of the bar RightCol% rightmost column of the bar (use -1 for auto-sizing) VAttr% bar color/attribute (see CalcAttr) HiAttr% bar highlight color/attribute (see CalcAttr) Prompt$ prompt text (displayed at the left side of the bar) Mouse% whether a mouse is available (0 no) ShowCursor% not used ------- Row% number of the chosen item (1-items, or 0 if <ESC>) Name : Bickel (Bickel comparison) Class : String Level : Any A string comparison routine, Bickel allows you to see how closely two strings match. The better the match, the larger the returned value will be. Since there is no constant minimum or maximum value, this routine is best used for applications involving dictionary searches. You would scan the dictionary and make a list of the best matches. This is appropriate for a spelling checker, for instance. Bickel St1$, St2$, Result% St1$ first string to compare St2$ second string to compare ------- Result% resulting "match magnitude" value Name : BigPrint (Big Print) Class : Display Level : BIOS As the name suggests, this routine displays text in large characters. How large? Eight times as high and as wide as normal! Each "big character" will be composed of many normal-sized characters. You may choose the normal character used to create the big characters (the default is a CHR$(219) solid block character, if you pass a null string here). You should avoid using CHR$(128) to CHR$(255) when in either of the CGA graphics modes, as many CGAs are unable to display these characters when in graphics mode. BigPrint St$, FormCh$, Row%, Column%, VAttr% St$ string to display in big characters FormCh$ character used to compose the big characters Row% starting row Column% starting column VAttr% color/attribute of big characters (see CalcAttr) Name : BinSeekD (Binary Seek Double precision) Class : Array management Level : Any This routine uses binary search techniques to locate a specific number in a sorted double-precision array. Each number in the array must be unique (no duplicates) for this to work. This is a very, very fast routine and is especially handy for look-up tables. The array is expected to begin at element 1. You may specify the maximum element to search, allowing use of only part of an array. A single number is returned in Posn%. If Posn% is greater than zero, the target number was found and Posn% is the position in the array where it was found. If Posn% is negative, the target number was not found, but it could be inserted into the array at the -Posn% element. If the number is zero, the target number was not found and there is no room in the array to add any more values. BinSeekD Array#(), Elements%, Target#, Posn% Array#() array of sorted, unique values to search Elements% maximum array element to search Target# value to look for ------- Posn% whether and where the target was found (see above) Name : BinSeekI (Binary Seek Integer) Class : Array management Level : Any This routine uses binary search techniques to locate a specific number in a sorted integer array. Each number in the array must be unique (no duplicates) for this to work. This is a very, very fast routine and is especially handy for look-up tables. The array is expected to begin at element 1. You may specify the maximum element to search, allowing use of only part of an array. A single number is returned in Posn%. If Posn% is greater than zero, the target number was found and Posn% is the position in the array where it was found. If Posn% is negative, the target number was not found, but it could be inserted into the array at the -Posn% element. If the number is zero, the target number was not found and there is no room in the array to add any more values. BinSeekI Array%(), Elements%, Target%, Posn% Array%() array of sorted, unique values to search Elements% maximum array element to search Target% value to look for ------- Posn% whether and where the target was found (see above) Name : BinSeekL (Binary Seek Long integer) Class : Array management Level : Any This routine uses binary search techniques to locate a specific number in a sorted long integer array. Each number in the array must be unique (no duplicates) for this to work. This is a very, very fast routine and is especially handy for look-up tables. The array is expected to begin at element 1. You may specify the maximum element to search, allowing use of only part of an array. A single number is returned in Posn%. If Posn% is greater than zero, the target number was found and Posn% is the position in the array where it was found. If Posn% is negative, the target number was not found, but it could be inserted into the array at the -Posn% element. If the number is zero, the target number was not found and there is no room in the array to add any more values. BinSeekL Array&(), Elements%, Target&, Posn% Array&() array of sorted, unique values to search Elements% maximum array element to search Target& value to look for ------- Posn% whether and where the target was found (see above) Name : BinSeekS (Binary Seek Single precision) Class : Array management Level : Any This routine uses binary search techniques to locate a specific number in a sorted single-precision array. Each number in the array must be unique (no duplicates) for this to work. This is a very, very fast routine and is especially handy for look-up tables. The array is expected to begin at element 1. You may specify the maximum element to search, allowing use of only part of an array. A single number is returned in Posn%. If Posn% is greater than zero, the target number was found and Posn% is the position in the array where it was found. If Posn% is negative, the target number was not found, but it could be inserted into the array at the -Posn% element. If the number is zero, the target number was not found and there is no room in the array to add any more values. BinSeekS Array!(), Elements%, Target!, Posn% Array!() array of sorted, unique values to search Elements% maximum array element to search Target! value to look for ------- Posn% whether and where the target was found (see above) Name : BinSeekSt (Binary Seek String) Class : Array management Level : Any This routine uses binary search techniques to locate a specific string in a sorted string array. Each string in the array must be unique (no duplicates) for this to work. This is a very, very fast routine and is especially handy for look-up tables. The string array is expected to begin at element 1. You may specify the maximum element to search, allowing use of only part of an array. You must specify whether capitalization matters-- set CapsCount% to 0 if it doesn't. A single number is returned in Posn%. If the number is greater than zero, the target string was found, and the number is the position in the array where it was found. If the number is negative, the target string was not found, but it could be inserted into the array at the -Posn% element. If the number is zero, the target string was not found and there is no room in the array to add any more values. BinSeekSt Array$(), Elements%, Target$, CapsCount%, Posn% Array$() array of sorted, unique values to search Elements% maximum array element to search Target$ string to look for CapsCount% 0 if capitalization doesn't matter ------- Posn% whether and where the target was found (see above) Name : BIOSInkey (BIOS INKEY$) Class : Input Level : BIOS BIOSInkey works like INKEY$, but it gets its key directly by asking the BIOS. The primary advantage of this is that you get the "scan" code as well as the ASCII code of the key. The scan code is independent of the shift status-- for instance, the scan code for "A" is the same as the scan code for "a" or Control-A or Alt-A. This can be very handy. If there is no key available, both the scan code and ASCII code will be zero. BIOSInkey AscCode%, ScanCode% ------- AscCode% ASCII code of the key, if any ScanCode% scan code of the key, if any Name : BkScroll (Backward Scroll) Class : Display Level : BIOS This routine scrolls any selected part of the display down-- it does a backwards scroll. You may scroll as many times as you like, or scroll "zero" times to totally clear the selected part of the display. Note that BIOS-level scrolling can cause the screen to flicker on some CGAs due to a combination of unfortunate design factors. BkScroll TopRow%, LeftCol%, BottomRow%, RightCol%, Times% TopRow% top row of the area to scroll LeftCol% left column of the area to scroll BottomRow% top row of the area to scroll RightCol% left column of the area to scroll Times% number of times (or rows) to scroll Name : BkSpace (Backspace) Class : Display Level : BIOS Although CHR$(8) is supposed to mean "backspace", it shows up as a graphics character when BASIC prints it. This routine does an actual backspace with full wrap-- if it's at the beginning of the line, it will move back to the previous line (if there is one). It backspaces destructively (erasing the previous character) from the current cursor position. The new cursor is returned to you, since QuickBASIC may ignore the new status. BkSpace Row%, Column% ' do the backspace LOCATE Row%, Column% ' inform QuickBASIC ------- Row% new row Column% new column Name : Blink (Blink toggle) Class : Display Level : BIOS / Clone (see text) It is possible to make characters in text mode blink by giving them an appropriate "color". I wouldn't mention something so obvious but for another possibility which is less widely known: blinking can be turned off, in which case the characters that would have otherwise blinked will instead have a bright background. In other words, turn off blinking, and you double the possible number of background colors. This technique will always work with EGA and VGA displays. It can also be used with MDA/Hercules and CGA displays, on which it will almost always work... unfortunately, on some less-than-perfect PC clones, it will cause the computer to lock up instead. So, be careful with this one! Blink SetBlink% SetBlink% use blink (-1) or intense backgrounds (0) Name : BlockMove (Block memory Move) Class : Memory Level : Clone This routine allows you to copy or "move" a block of data from one memory location to another. It isn't very bright, so if the memory areas overlap, you will have to tell the routine to "move backwards" instead of forwards. In that case, you will also have to change the offsets to point to the ends of the memory areas instead of the beginnings. Normally, you can use forward moves. In that case, the offsets you specify are those of the beginning of the memory areas. If backward moves are required, the offsets specified are those of the end of the memory areas. If you are familiar with assembly language, you may recognize this as a straightforward implementation of the "REP MOVSB" instruction. You may move up to 65,520 bytes at a time, provided that the addresses are in normalized form (if you don't know what this means, you probably don't need to worry about it). This routine can be used to copy information to an array from any area of memory (the BIOS data area, the screen, another array, etc), or vice versa. It can also be used to do things like insert/delete elements from an array, scroll the screen, fill the screen with a specified character, and so on. BlockMove FromSeg%, FromOfs%, ToSeg%, ToOfs%, Bytes&, Dirn% FromSeg% segment of the area from which to copy FromOfs% offset of the area from which to copy ToSeg% segment of the area to which to copy ToOfs% offset of the area to which to copy Bytes& number of bytes to copy (0-65,520) Dirn% direction to copy (0 if forward, else backward) Name : BootDrive (get Boot Drive) Class : Disk Level : DOS 4.0+ This routine tells you which drive was used to boot the system. See also BootDrive2, a function version of this routine. One use for BootDrive would be in installation programs, to determine the most likely destination drive for your software. Drive$ = "x" BootDrive Drive$ ------- Drive$ boot drive-- set it to at least one char beforehand! Name : BootDrive2$ (get Boot Drive) Class : Disk Level : DOS 4.0+ This routine tells you which drive was used to boot the system. One use for BootDrive2 would be in installation programs, to determine the most likely destination drive for your software. Drive$ = BootDrive2$ ------- Drive$ boot drive (null if wrong DOS version) Name : BoxMenu (Box Menu) Class : Input Level : Clone This routine displays a list of items you pass it as a string array. The list is displayed in a window in a single column. If there are more items than will fit in the window, the items may be scrolled as necessary. The user may pick a single item from the list. Many of the usual WindowManager parameters are used here-- top row, left column, and bottom row (right column is calculated for you), window frame color and frame type, growth, shadow, title string and title color-- see the WindowManager routine for details. If you allow using the mouse, be sure the mouse is initialized (MMCheck or MMCheck2%) and the mouse cursor is visible (MMCursorOn) before calling this routine. This routine automatically saves and restores the underlying screen. See CalcAttr if you're not familiar with color/attributes. See also BoxMenu1 if you need to allow multiple selections. BoxMenu Mouse%, PickList$(), TopRow%, LeftCol%, _ BottomRow%, Frame%, FrameAttr%, ItemListAttr%, _ HiliteAttr%, TitleFore%, Title$, Grow%, Shade%, Result% Mouse% whether to support the mouse (0 no, -1 yes) PickList$() items to pick from (starting at PickList$(1)) TopRow% top row of pick window LeftCol% left column of pick window BottomRow% bottom row of pick window Frame% frame type FrameAttr% frame color/attribute ItemListAttr% item list color/attribute HiliteAttr% highlight bar color/attribute TitleFore% title foreground color (backgnd is frame color) Title$ title (use "" for no title) Grow% window growth Shade% window shadow ------- Result% number of item picked (0 if none) Name : BoxMenu1 (Box Menu variant 1) Class : Input Level : Clone This routine displays a list of items you pass it as a string array. The list is displayed in a window in a single column. If there are more items than will fit in the window, the items may be scrolled as necessary. The user may pick multiple items from the list, using the space bar to toggle selection. Many of the usual WindowManager parameters are used here-- top row, left column, and bottom row (right column is calculated for you), window frame color and frame type, growth, shadow, title string and title color-- see the WindowManager routine for details. If you allow using the mouse, be sure the mouse is initialized (MMCheck or MMCheck2%) and the mouse cursor is visible (MMCursorOn) before calling this routine. This routine automatically saves and restores the underlying screen. See CalcAttr if you're not familiar with color/attributes. See also BoxMenu if you only need single-item selection. You must pass an integer array corresponding to the pick list array. Each of the integers flags whether the corresponding item is picked-- 0 if no, -1 if yes. You may initialize this array according to the selection defaults you prefer. The Marker$ value is two characters which specify the left and right characters to use to mark an item as selected. If you leave Marker$ = "", the default will be "<>". BoxMenu1 Mouse%, PickList$(), Picked%(), Marker$, TopRow%, _ LeftCol%, BottomRow%, Frame%, FrameAttr%, _ ItemListAttr%, HiliteAttr%, TitleFore%, Title$, Grow%, _ Shade%, Picks% Mouse% whether to support the mouse (0 no, -1 yes) PickList$() items to pick from (starting at PickList$(1)) Picked%() if corresponding PickList$() item is picked Marker$ left and right pick markers ("" for default) TopRow% top row of pick window LeftCol% left column of pick window BottomRow% bottom row of pick window Frame% frame type FrameAttr% frame color/attribute ItemListAttr% item list color/attribute HiliteAttr% highlight bar color/attribute TitleFore% title foreground color (backgnd is frame color) Title$ title (use "" for no title) Grow% window growth Shade% window shadow ------- Picked%() if corresponding PickList$() item is picked Picks% number of items picked (0 if none) Name : BRead (Byte Read) Class : Disk Level : DOS This routine reads a byte from a file into an integer. The byte is zero-extended into the integer, providing a value that may range from 0-255. The file must have been opened using FCreate or FOpen1. BRead Handle%, Value%, ErrCode% Handle% file handle ------- Value% byte read from file ErrCode% DOS error code (0 if no error) Name : BreakCheck% (Break key Check) Class : Input Level : BIOS This routine is for use after BreakOff. It allows you to see whether the Break key has been pressed since you last checked. The Break status is cleared after the value is returned. Brk% = BreakCheck% IF Brk% THEN PRINT "** Break key pressed **" GOTO EndProgram END IF ------- Brk% whether Break was pressed (0 no, -1 yes) Name : BreakOff (Break key Off) Class : Input Level : BIOS This routine disables the Break key. It is not effective in the QB or QBX environments, as these use their own keyboard handler. It is also not effective if your program was compiled with Debugging on (/D switch). Note that BreakOff installs a routine to intercept some interrupt vectors. You MUST use the BreakOffDone routine to reverse this process before your program ends, or the computer will be left in an indeterminate state and will probably crash the next time Break is pressed! BreakOff Name : BreakOffDone (Break key Off routine Done) Class : Input Level : BIOS This routine is used after BreakOff to restore the original interrupt vectors. If you use BreakOff, you MUST call BreakOffDone before your program ends! Otherwise, the computer will probably crash the next time someone presses Break. BreakOffDone Name : BSq (Blank Squeeze) Class : String Level : Any A simple compression routine, BSq "squeezes" the blank spaces in a string. It is designed expressly for use with text data. The text may not contain more than 131 spaces in a row, or CHR$(128) through CHR$(255), which are used in the compression. Average text files are liable to be compressed by around 16%. Files that contain more spaces, such as structured programs, will benefit more. The compression algorithm is simple but extremely fast, adding no noticeable overhead to string processing. See also BUsq, BUsqLen. BSq St$, StLen% St$ = LEFT$(St$, StLen%) St$ string to compress ------- St$ compressed string StLen% length of the compressed string Name : BUsq (Blank Unsqueeze) Class : String Level : Any This routine is used to uncompress strings that were processed by BSq. Before uncompression, the BUsqLen routine must be used to find out how long the resulting string will be. See also BSq, BUsqLen. BUsqLen St$, StLen% IF StLen% < 0 THEN PRINT "Error in compressed string" ELSE Result$ = SPACE$(StLen%) BUsq St$, Result$ END IF St$ string to uncompress ------- Result$ uncompressed string Name : BUsqLen (Blank Unsqueeze Length) Class : String Level : Any This routine is used in coordination with BUsq to uncompress strings that were processed by BSq. It determines what the length of the uncompressed string will be, which is necessary to initialize the string for BUsq. See also BSq, BUsq. BUsqLen St$, StLen% IF StLen% < 0 THEN PRINT "Error in compressed string" ELSE Result$ = SPACE$(StLen%) BUsq St$, Result$ END IF St$ string to uncompress ------- StLen% length of the uncompressed string Name : BWrite (Byte Write) Class : Disk Level : DOS This routine writes a byte to a file from an integer. The least significant byte of the integer is written. The file must have been opened using FCreate or FOpen1. BWrite Handle%, Value%, ErrCode% Handle% file handle Value% byte to write to file ------- ErrCode% DOS error code (0 if no error) Name : CalcAttr (Calculate Attribute) Class : Display Level : Any Many of the display routines in this library require an "attribute" rather than foreground and background colors. An attribute is a combination of the foreground and background colors in a format which is used by all types of displays when in text mode. Foreground colors are usually specified as 0-31, with backgrounds as 0-7. If you turn blinking off (see Blink), it may be more convenient to express the same thing as foreground 0-15, background 0-15. The CalcAttr routine will accept either way of expressing it. Note, however, that UnCalcAttr will always return the former pair of results, since it has no way of knowing whether Blink has been used (foreground 0-31, background 0-15). See UnCalcAttr for more details and a solution. See also CalcAttr2, the FUNCTION version of this routine. CalcAttr Foreground%, Background%, VAttr% Foreground% foreground color Background% background color ------- VAttr% color "attribute" Name : CalcAttr2% (Calculate Attribute) Class : Display Level : Any Many of the display routines in this library require an "attribute" rather than foreground and background colors. An attribute is a combination of the foreground and background colors in a format which is used by all types of displays when in text mode. Foreground colors are usually specified as 0-31, with backgrounds as 0-7. If you turn blinking off (see Blink), it may be more convenient to express the same thing as foreground 0-15, background 0-15. The CalcAttr2 routine will accept either way of expressing it. Note, however, that UnCalcAttr will always return the former pair of results, since it has no way of knowing whether Blink has been used (foreground 0-31, background 0-15). See UnCalcAttr for more details and a solution. See also CalcAttr, the SUB version of this routine. VAttr% = CalcAttr2%(Foreground%, Background%) Foreground% foreground color Background% background color ------- VAttr% color "attribute" Name : CalcDate (Calculate Date) Class : Time Level : Any This routine calculates what the date will be a given number of days from now, either in the past or the future. Actually, you may use any starting date, not just the current date. An error code is returned if the starting date or resulting date are not valid. Dates may not preceed January 1, 1900. CalcDate accepts the date in any standard form ("01/30/91" or "01-30-1991", for example) and returns its results in the same format. CalcDate StartDate$, Days&, Direction%, NewDate$, ErrCode% StartDate$ starting date Days& number of days from the current date (0 or more) Direction% return future result (0) or past (nonzero) ------- NewDate$ resulting date ErrCode% whether the dates are valid (0 yes) Name : CalcSize (Calculate array Size) Class : Display Level : Any This routine calculates the necessary DIM size for an integer array, assuming that you intend to store display data in the array. This is most useful in conjunction with DGetScreen and GetScreen. CalcSize TopRow%, LeftCol%, BottomRow%, RightCol%, Elements% DIM Array%(1 TO Elements%) TopRow% top row of the display area LeftCol% left column of the display area BottomRow% top row of the display area RightCol% left column of the display area ------- Elements% required size of the integer array Name : CalcVGAColor (Calculate VGA palette Color) Class : Display Level : Any The QuickBASIC manual gives a cumbersome formula for calculating VGA palette colors. This routine does it faster and with less fuss. All you need to do is pass it the appropriate intensity values (0-63) and you get back a long integer, just the way BASIC wants it. CalcVGAColor Red%, Green%, Blue%, Colour& Red% red intensity Green% green intensity Blue% blue intensity ------- Colour& color value for use in the PALETTE statement Name : Carrier (detect Carrier) Class : Serial Level : Clone If you write communications programs, particularly things like doors and BBSes, you probably want to keep an eye on the carrier. BASIC won't do it, but we will! Carrier CommPort%, CarrierHigh% CommPort% serial port (1-4, though BASIC only handles 1-2) ------- CarrierHigh% zero if no carrier Name : CatchError (Catch Error from SHELL) Class : Miscellaneous Level : Clone NOTE: You should use the GetError2% function in preference to this set of routines. The CatchError routine is used in conjunction with GetError. It lets you get the exit code (error level) returned by a program to which you have SHELLed. Since CatchError hooks an interrupt to do its work, you must always make sure to use GetError afterwards to "clean up". See also GetError. Note that differences in DOS mean that this routine will not always work. In some versions of DOS, you can only get the error level if a batch file was executed; in others, you can't get the error level from a batch file at all. Sorry about that. I don't know of any way to work around it. CatchError SHELL ProgramName$ GetError ExitCode% Name : CDROM (check for CD-ROM) Class : Disk / Equipment Level : DOS This routine tells you whether the Microsoft CD-ROM Extensions are installed. If so, it tells you what the letter of the first CD-ROM logical drive is and how many logical drives exist. Note: The CD-ROM installation check conflicts with the GRAPHICS.COM installation check for DOS 4.0, due to some screw-up at IBM or Microsoft. This may cause unexpected results. I'm not yet sure whether DOS 5.0 is similarly afflicted. FirstDrive$ = "x" CDROM FirstDrive$, Drives% ------- FirstDrive$ letter of first logical drive (init to >= 1 char) Drives% number of logical drives (0 if no CD-ROM) Name : CDROM2% (check for CD-ROM) Class : Disk / Equipment Level : DOS This routine tells you whether the Microsoft CD-ROM Extensions are installed. If so, it tells you how many logical drives exist. Note: The CD-ROM installation check conflicts with the GRAPHICS.COM installation check for DOS 4.0, due to some screw-up at IBM or Microsoft. This may cause unexpected results. I'm not yet sure whether DOS 5.0 is similarly afflicted. Drives% = CDROM2% ------- Drives% number of logical drives (0 if no CD-ROM) Name : CeilD# (Ceiling, Double-precision) Class : String Level : Any This function returns the smallest integer greater than or equal to the number you give it. This is most often used for rounding. Result# = CeilD#(Nr#) Nr# number to process ------- Result# result Name : CeilS! (Ceiling, Single-precision) Class : String Level : Any This function returns the smallest integer greater than or equal to the number you give it. This is most often used for rounding. Result! = CeilS!(Nr!) Nr! number to process ------- Result! result Name : CenterSt$ (Center String) Class : String Level : Any This function returns a string centered in a field of spaces. Result$ = CenterSt$(StToCenter$, Columns%) StToCenter$ string to center Columns% width of field in which to center string ------- Result$ field of spaces with string centered in it Name : CheckDate (Check Date validity) Class : Time Level : Any This routine checks a date to see if it is valid. CheckDate MonthNr%, DayNr%, YearNr%, ErrCode% MonthNr% month number (1-12) DayNr% day number (1-31) YearNr% year number (1900 on; years <100 assumed 1900s) ------- ErrCode% whether the date is valid (0 yes) Name : CheckDisk (Check Disk readiness) Class : Disk Level : DOS The CheckDisk routine determines whether a disk is ready. About the only thing it won't tell you is if a disk is write-protected or out of space. Since the PBClone disk routines all contain critical error handling, which reports back an appropriate error code for all such problems, this routine isn't really needed any more. It's included for compatibility with older ProBas programs. Results will normally be returned as one of the following, although not all DOS versions report the exact cause of the error, in which case the error number may not mean what you expect. 0 no error 1 unformatted disk 2 open drive door 3 bad drive spec CheckDisk Drive$, ErrCode% Drive$ letter of the drive to check ------- ErrCode% 0 if no error, nonzero for error (see above) Name : CheckDsk% (Check Disk readiness) Class : Disk Level : DOS The CheckDsk% function determines whether a disk is ready. About the only thing it won't tell you is if a disk is write-protected or out of space. Since the PBClone disk routines all contain critical error handling, which reports back an appropriate error code for all such problems, this routine isn't really needed any more. It's included for compatibility with older ProBas programs. Note that DOS versions before 3.0 do not return as useful error codes as later versions. Under such circumstances, both "unformatted disk" and "open drive door" will be returned as "open drive door". ErrCode% = CheckDsk%(Drive$) Drive$ letter of the drive to check Name : CheckKey (Check for Key or mouse) Class : Input, Mouse Level : BIOS This routine is kind of an extended version of INKEY$. It checks the keyboard to see if any key is available and gets the key if it is. At your option, it can also check the mouse to see if a button has been pressed. CheckKey Mouse%, ASCIIcode%, ScanCode%, LButton%, RButton% Mouse% whether to check the mouse (0: no) ------- ASCIIcode% ASCII code of the key pressed ScanCode% scan code of the key pressed (0 if none) LButton% whether the left mouse button was pressed RButton% whether the right mouse button was pressed Name : CheckKey3 (Check for Key or 3-button mouse) Class : Input, Mouse Level : BIOS This routine is kind of an extended version of INKEY$. It checks the keyboard to see if any key is available and gets the key if it is. At your option, it can also check the mouse to see if a button has been pressed. CheckKey3 Mouse%, ASCIIcode%, ScanCode%, LButton%, MButton%, RButton% Mouse% whether to check the mouse (0: no) ------- ASCIIcode% ASCII code of the key pressed ScanCode% scan code of the key pressed (0 if none) LButton% whether the left mouse button was pressed MButton% whether the middle mouse button was pressed RButton% whether the right mouse button was pressed Name : CheckShare (Check for SHARE) Class : Disk Level : DOS The CheckShare routine determines whether SHARE.EXE is active. This is particularly helpful before using the BASIC OPEN statement, which will fail if you request file sharing when it's not available. The PBClone file routines handle such situations automatically, so CheckShare is not needed for them. CheckShare ShareActive% ------- ShareActive% whether SHARE is active (0 if no) Name : CheckShare2% (Check for SHARE) Class : Disk Level : DOS The CheckShare2% function determines whether SHARE.EXE is active. This is particularly helpful before using the BASIC OPEN statement, which will fail if you request file sharing when it's not available. The PBClone file routines handle such situations automatically, so CheckShare2% is not needed for them. ShareActive% = CheckShare2% ------- ShareActive% whether SHARE is active (0 if no) Name : Checksum (calculate Checksum) Class : Serial Level : Any The Checksum routine calculates a checksum on a string. The resulting number is compatible with Xmodem and Ymodem checksum routines and will vary from 0-255. This checksum provides a minimal, but fast, check of what characters are contained in the string. See also Checksum2%, the function version of this routine, and CRC1. Checksum St$, ChkSum% St$ string to process ------- ChkSum% checksum of the characters in the string Name : Checksum2% (calculate Checksum) Class : Serial Level : Any The Checksum2% function calculates a checksum on a string. The resulting number is compatible with Xmodem and Ymodem checksum routines and will vary from 0-255. This checksum provides a minimal, but fast, check of what characters are contained in the string. See also Checksum, the sub version of this function, and CRC1. ChkSum% = Checksum2% (St$) St$ string to process ------- ChkSum% checksum of the characters in the string Name : Cipher (Cipher) Class : String Level : Any This is a very simple text encryption routine. It isn't particularly hard to crack, but will provide a basic level of security for undemanding applications. The same routine can be used either to encrypt or decrypt text. The original text may contain any character; likewise, the resulting text. This is not well suited for use with sequential files-- if such is required, see CipherP. I'd suggest using a long password composed of an unlikely string of characters, e.g. "#*@@!A^%x{.'". Cipher St$, Password$ St$ string to encrypt or decrypt Password$ password ------- St$ encrypted or decrypted string Name : CipherP (Cipher Printable) Class : String Level : Any This is a very simple text encryption routine. It isn't particularly hard to crack, but will provide a basic level of security for undemanding applications. The same routine can be used either to encrypt or decrypt text. The original text may contain any character below CHR$(128), as may the password. The resulting text will be printable, if bizarre (all characters will be above CHR$(127)), and may be used with sequential files. This routine is potentially less secure than the Cipher routine (see). I'd suggest using a long password composed of an unlikely string of characters, e.g. "#*@@!A^%x{.'". CipherP St$, Password$ St$ string to encrypt or decrypt Password$ password ------- St$ encrypted or decrypted string Name : ClearArea (Clear a screen Area) Class : Display Level : Clone This routine clears an area of the screen to a specified color. The clearing is done by removing random characters until the area is totally clear. ClearArea TRow%, LCol%, BRow%, RCol%, VAttr%, Fast% TRow% top row of area to clear LCol% left column of area to clear BRow% bottom row of area to clear RCol% right column of area to clear VAttr% color/attribute to clear to Fast% whether to use fast displays (0 no) Name : Clock (Clock) Class : Display / Time Level : Clone This routine allows you to turn a visible time display on or off. When on, the time will be continuously displayed at a selected location while your program continues processing. The clock is managed as a background process, in effect doing some simple multitasking. You should turn the clock off before you terminate your program, including any time you execute another program with RUN. The clock can be safely kept on when you SHELL to another program, however, as long as you can be sure that control will return to your program when the other is done. The clock must also be turned off if you change any of its parameters with the ClockSet routine (see). The clock will only be visible when the display is in text mode. The use of PLAY or SOUND statements may shut off the clock, depending on your version of the BASIC compiler. Clock DisplayOn% DisplayOn% whether to display the clock (0 if no) Name : ClockSet (Clock Settings) Class : Display / Time Level : Clone The ClockSet routine is used in conjunction with Clock (see). It should only be used when the clock is turned off. This routine allows you to set 12-hour or 24-hour time, whether to display the seconds or not, how often to update the clock display (in 1/18th seconds; 9 is usually the best choice), where to display the clock and in what color, and whether to use flicker-free displays (needed for cheap CGAs only). The defaults are 12-hour time, display seconds, put the time (in white on black) in the upper right corner, and display quickly (may flicker on some CGAs). ClockSet Hours24%, Seconds%, Updates%, Row%, Column%, _ VAttr%, Fast% Hours24% whether to display 24-hour time (0 if no) Seconds% whether to display seconds (0 if no) Updates% display update frequency in 1/18th seconds Row% row on which to display the clock Col% column at which to display the clock VAttr% color/attribute to use (see CalcAttr) Fast% whether to use fast mode (0 no) Name : CloseA (Close Archive) Class : Disk / Time Level : DOS This routine closes an archive opened by FindFirstA or FindNextA. It must be used when you are done searching the archive. Routines in this series include: FindFirstA, FindNextA, GetNameA, GetCRCA, GetCRCAL, GetDateA, GetTimeA, GetSizeAL, GetStoreA CloseA Name : ClrCols (Clear Columns) Class : Display Level : BIOS This routine clears the current row between the specified columns, inclusive. It does not affect the cursor position. ClrCols StartCol%, EndCol% StartCol% starting column EndCol% ending column Name : ClrEOL (Clear to End Of Line) Class : Display Level : BIOS This routine clears from the cursor to the end of the line, inclusive. It does not affect the current cursor position. ClrEOL Name : ClrEOP (Clear to End Of Page) Class : Display Level : BIOS This routine clears from the cursor to the end of the display, inclusive. It does not affect the current cursor position. ClrEOP Name : ClrKbd (Clear Keyboard buffer) Class : Input Level : DOS ClrKbd clears the keyboard buffer, discarding any keys that may be waiting. This is a good idea for situations where an unexpected input is made and you don't want to chance it being answered accidentally by keys that were typed beforehand-- for instance, in the event of an error or other condition where it is important that the user see a message or take an action before pressing a key. ClrKbd Name : ClrSOL (Clear to Start Of Line) Class : Display Level : BIOS This routine clears from the start of the line to the cursor, inclusive. It does not affect the current cursor position. ClrSOL Name : ClrSOP (Clear to Start Of Page) Class : Display Level : BIOS This routine clears from the start of the display to the cursor, inclusive. It does not affect the current cursor position. ClrSOP Name : Command2$ (Command line) Class : Miscellaneous Level : DOS This function returns the original DOS command line. It works like COMMAND$, but does not trim or capitalize the command line. The area in which the command line is stored may be recycled for other purposes, so you should use Command2$ as near to the start of your program as possible. CmdLine$ = Command2$ ------- CmdLine$ original DOS command line Name : CopyFile (Copy a File) Class : Disk Level : DOS This works like the DOS COPY command, although it does not allow wildcards. One file is copied to another, retaining the same date and time. Full path specifications are supported, including drive and subdirectory specs. See also FileCopy, which supports wildcards. CopyFile FromFile$, ToFile$, ErrCode% FromFile$ name of file to copy ToFile$ name of new file to create ------- ErrCode% 0 if no error, else DOS Error Name : CPrintScreen1 (CGA Print Screen [SCREEN 1]) Class : Display / Printer Level : Clone This routine dumps a SCREEN 1 display (CGA 320x200) to the printer. It uses the stdprn device (normally PRN or LPT1) by default, although this can be altered with the PrtSwap routine. CPrintScreen1 Name : CPrintScreen2 (CGA Print Screen [SCREEN 2]) Class : Display / Printer Level : Clone This routine dumps a SCREEN 2 display (CGA 640x200) to the printer. It uses the stdprn device (normally PRN or LPT1) by default, although this can be altered with the PrtSwap routine. CPrintScreen2 Name : CPUSpeed% (CPU Speed) Class : Equipment Level : Clone This function returns the approximate CPU speed in MHz. It may take several seconds to find the speed of slower processors, so don't expect an immediate response. Results can be skewed by multitasking and background processing. MHz% = CPUSpeed% ------- MHz% approximate CPU speed Name : CRC (calculate CRC) Class : String / Serial Level : Any This routine has become obsolete; the CRC1 routine is much faster. However, CRC is still included for backwards compatibility. This routine calculates a complex 16-bit checksum, called a Cyclical Redundancy Check (or CRC) on a string. The results are compatible with Xmodem and Ymodem CRC routines. The CRC provides a fairly reliable check of what characters are contained in the string. See also Checksum. If you are using this routine for Xmodem or Ymodem, note that the string should be padded with two null characters before calculating a "send" CRC: St$ = St$ + STRING$(2, 0). On receive, you should calculate the CRC on the entire data block, plus the received CRC; if the block was received correctly, the calculated CRC will be zero in both lsb and msb. Although Intel notation uses "lsb, msb" order, the Xmodem/Ymodem CRC uses the opposite format, which is why the parameters are ordered in this fashion. CRC St$, CRCmsb%, CRClsb% St$ string to process ------- CRCmsb% most significant byte of CRC CRClsb% least significant byte of CRC Name : CRC1 (calculate CRC) Class : String / Serial Level : Any This routine calculates a complex 16-bit checksum, called a Cyclical Redundancy Check (or CRC) on a string. The results are compatible with Xmodem and Ymodem CRC routines. The CRC provides a fairly reliable check of what characters are contained in the string. See also Checksum. Note that CRC1 does not work like the older CRC routine. You should not pad outgoing strings with a STRING$(2, 0) sequence. Although Intel notation uses "lsb, msb" order, the Xmodem/Ymodem CRC uses the opposite format, which is why the parameters are ordered in this fashion. CRC1 St$, CRCmsb%, CRClsb% St$ string to process ------- CRCmsb% most significant byte of CRC CRClsb% least significant byte of CRC Name : Crunch (Crunch repeated characters) Class : String Level : Any It was hard to decide on a name for this routine, and I don't know if I've done the best job. What Crunch does is to eliminate repeated sequences of the same character. For instance, if you gave it "This is a test" and asked it to crunch spaces, it would return "This is a test". I use this to filter information from the COMMAND$ function, but it's a good general purpose input filter. Crunch St$, Ch$, StLen% St$ = LEFT$(St$, StLen%) St$ string to be processed Ch$ character to crunch out of the string ------- St$ crunched string StLen% length of the crunched string Name : CtrlKey (Control Key) Class : Input Level : Any This routine works in conjunction with a key input routine, such as INKEY$ or the CheckKey and GetKey routines. Given the ASCII code of a key, CtrlKey returns the associated key letter, if any. For instance, it returns "A" if you pass it ASCII code 1, because that code represents Ctrl-A. CtrlKey ASCIICode%, Ky$ ASCIICode% ASCII code of the key ------- Ky$ associated key letter ("" if none) Name : CursorInfo (Cursor Information) Class : Input Level : Clone While BASIC allows you to set the size and shape of the cursor with LOCATE, it's fairly hazardous to do so. There is no way to find out the maximum size of the cursor, so your cursor may end up a peculiar shape on some adapters. If you change the cursor size or visibility in a subprogram, you may be screwing up the main program. CursorInfo offers a solution to these problems. It returns the current cursor visibility and size, plus the maximum size possible with the current video adapter. The minimum size will always be zero, so it is not reported. CursorInfo Visible%, StartLine%, EndLine%, MaxLine% ------- Visible% whether the cursor is visible (0 no, 1 yes) StartLine% starting scan line of cursor EndLine% ending scan line of cursor MaxLine% maximum possible scan line for cursor Name : CWindowManager (CGA Window Manager) Class : Display Level : Clone CWindowManager displays a pop-up window on a CGA graphics screen. It is intended for SCREEN 1, although it can be used on SCREEN 2 as well (it will still have 40 columns and will display shades rather than colors). The window may have any of a variety of frames, a title, or a shadow, and it may appear instantly or "grow" onto the screen. These are the available frame types: 0 no frame 1 single lines 2 double lines 3 single horizontal, double vertical lines 4 double horizontal, single vertical lines 5 block graphic lines Options for growing windows are as follows: -1 grow as fast as possible 0 pop onto the screen 1+ grow with delay given in milliseconds (15 works for me) Note that this routine is different from its ProBas equivalent in a number of respects. The grow delay time is different. Growing is done more smoothly. The shadow and title parameters are not changed by this routine. A new frame type (5) was added. If a title is too long, it is truncated instead of being ignored completely. Using a -1 as the title foreground color will not turn off the title; instead, use a null title string. CWindowManager TRow%, LCol%, BRow%, RCol%, Frame%, Fore%, Back%, Grow%, Shade%, TFore%, Title$, Fast% TRow% top row of window LCol% left column of window BRow% bottom row of window RCol% right column of window Frame% frame type (see above) Fore% frame foreground color Back% frame background color Grow% window growing option (see above) Shade% window shadow option (0 for none) TFore% title foreground color Title$ window title ("" if none) Fast% whether to use fast mode (0 no) Name : DataSeg (Data Segment) Class : Memory Level : Any It's rare that you need to know the data segment used by BASIC, but it does happen. DataSeg tells you that value. This is the segment used by (near) strings, static arrays (except in the QuickBASIC environment), some COMMON data, BASIC internal variables and so forth. It is also the area specified by a plain "DEF SEG", though not (usually) by "DEF SEG=xxxx". There is also a function version of this routine, DataSeg2%. DataSeg DSeg% ------- DSeg% data segment for BASIC Name : DataSeg2% (Data Segment) Class : Memory Level : Any It's rare that you need to know the data segment used by BASIC, but it does happen. DataSeg2% tells you that value. This is the segment used by (near) strings, static arrays (except in the QuickBASIC environment), some COMMON data, BASIC internal variables and so forth. It is also the area specified by a plain "DEF SEG", though not (usually) by "DEF SEG=xxxx". There is also a sub version of this routine, DataSeg. DSeg% = DataSeg2% ------- DSeg% data segment for BASIC Name : Date2Int (Date to Integer) Class : Time Level : Any This routine compresses a date into a single integer. Note that this integer is not in a format that lends itself to simple computation-- you cannot subtract one from another to find out the length of time between them. However, as long as the year is in the range 1980-2042, you can compare the two integers to see if one date is before or after another. You may express the year as either a two-digit or four-digit number. The ProBas and PBClone versions of this routine do not work the same way in regards to the year. ProBas assumed that any two-digit year was in the 1900s. In contrast, PBClone assumes that years 80-99 should be converted to 1980-1999 and that 0-79 should be converted to 2000-2079. I consider the PBClone method more appropriate, with the turn of the century moving closer. The date format used does not allow dates before 1980 anyway, so nothing is being lost by this change. Date2Int MonthNr%, DayNr%, YearNr%, IntDate% MonthNr% month number (1-12) DayNr% day (1-31) YearNr% year (1980-2079; see above for two-digit years) ------- IntDate% date compressed into an integer Name : DateA2R (Date Actual to Relative) Class : Time Level : Any This routine converts an actual date to a relative date, expressed as a number of days. This allows you to compare dates, find out what the date will be in a given number of days (or what it was a given number of days ago), see how many days passed between two dates, and so forth. I've frequently seen routines of this nature called "Julian date" routines. I'm not sure where that nomenclature originated, as it has nothing to do with the Julian calendar. Most of these routines rely on approximations through floating point math, and may or may not handle leap years and centuries appropriately. The DateA2R routine takes no such shortcuts and may be relied upon to return accurate results. DateA2R MonthNr%, DayNr%, YearNr%, RelDate& MonthNr% month number (1-12) DayNr% day number (1-31) YearNr% year number (1900 on; years <100 assumed in 1900s) ------- RelDate& relative date Name : DateN2S (Date Numbers to String) Class : Time Level : Any / DOS Many of the PBClone routines return the date as a set of numbers. This routine provides an easy way to convert those numbers into string form. The date format used (year length and delimiter) will be based on the string which you pass to the routine. For instance, "xx-xx-xxxx" will return a date like "11-26-1990", whereas "xx.xx.xxxx" would return "11.26.1990", and "xx/xx/xx" would return "11/26/90". If you pass zeroes for the MonthNr%, DayNr%, and YearNr% values, the current date will be returned in the format that you specified. The ProBas and PBClone versions of this routine do not work the same way in regards to the year. ProBas assumed that any two-digit year was in the 1900s. In contrast, PBClone assumes that years 80-99 should be converted to 1980-1999 and that 0-79 should be converted to 2000-2079. DateSt$ = "xx-xx-xxxx" DateN2S MonthNr%, DayNr%, YearNr%, DateSt$ MonthNr% month DayNr% day YearNr% year ------- DateSt$ date string. Init to 8 or 10 chars (see above). Name : DateR2A (Date Relative to Actual) Class : Time Level : Any This is the opposite of the DateA2R routine-- it takes a "relative" date and converts it back to the usual form. DateR2A MonthNr%, DayNr%, YearNr%, RelDate& RelDate& relative date ------- MonthNr% month number (1-12) DayNr% day number (1-31) YearNr% year number (1900 on) Name : DateS2N (Date String to Numbers) Class : Time Level : Any Many of the PBClone routines need to be passed the date as a set of numbers. This routine provides an easy way to convert a date from string form into numbers. You may use either "xx/xx/xx" or "xx-xx-xxxx" form to specify the date (the string length is important, but the delimiter and contents of the string are ignored). The ProBas and PBClone versions of this routine do not work the same way in regards to the year. ProBas assumed that any two-digit year was in the 1900s. In contrast, PBClone assumes that years 80-99 should be converted to 1980-1999 and that 0-79 should be converted to 2000-2079. DateS2N MonthNr%, DayNr%, YearNr%, DateSt$ DateSt$ date string. Init to 8 or 10 characters (see above). ------- MonthNr% month DayNr% day YearNr% year Name : DCal (Direct-to-memory Calendar) Class : Time Level : Any This routine draws a calendar for a specific month and year. The results are placed in an array which can be displayed using ScrRest or the other PBClone routines to restore a screen image. You must supply an integer array large enough to hold the image generated by DCal, which expects a 25x80 screen. DIM Scrn%(1 TO 2000) will do it. If you supply a null date, the current date will be used. DCal Scrn%(), CalDate$ Scrn%() array to hold screen image CalDate$ date for the calendar Page% ignored Fast% ignored Name : DCalendar (Direct-to-memory Calendar) Class : Time Level : Clone This routine displays a calendar for a specific month and year. It waits for input and acts accordingly, allowing the user to move to different dates via the arrow keys or by entering the date directly. The bottom row of the screen gives a list of the available key commands. Screen handling is largely done by writing to an array, then dumping the entire array to the display with DScrRest. This provides for very smooth displays. You must supply an integer array large enough to hold the image generated by DCalendar, which expects a 25x80 screen. DIM Scrn%(1 TO 2000) will do it. Only text mode is supported by this routine. If you supply a null date, the current date will be used. DCalendar Scrn%(), CalDate$, Page%, Fast% Scrn%() array to hold screen image CalDate$ date for the calendar Page% page on which to display (normally zero) Fast% whether to use fast mode (0 no) Name : DClear (Direct-to-memory Clear) Class : Display Level : Any The DClear routine allows you to clear a text-mode display. This routine does not necessarily work on the display itself. Instead, it allows you to specify the memory location (segment and offset) of the "screen", which may be an actual screen, a saved screen in an array, a multitasker's virtual screen, etc. Among other things, this makes it easy to work with two displays at once: use a segment of &HB000 for the mono display and &HB800 for the color display (the offset in each case is zero). DClear DSeg%, DOfs%, VAttr% DSeg% segment of "screen" memory DOfs% offset of "screen" memory VAttr% color/attribute to use (see CalcAttr) Name : DClearSS (Direct Clear for Specified Size) Class : Display Level : Any Like the CLS statement, this routine allows you to clear a text display. However, rather than clearing the actual screen, DClearSS clears a screen that is stored in an array. This allows you to design a screen in memory, then flash it onto the display using PutScreen or a similar routine. This routine is designed for a text screen of any specified size. DClearSS DSeg%, DOfs%, VAttr%, Rows%, Columns% DSeg% segment of the array that holds the screen DOfs% offset of the array that holds the screen VAttr% color/attribute to use (see CalcAttr) Rows% length of the screen Columns% width of the screen Name : Dec2Any (Decimal to Any base) Class : Numeric Level : Any This routine converts a normal integer to a number in any base. It works like the HEX$ function in BASIC, but rather than working only in hexadecimal (base 16), it can be used for binary, octal, or almost anything else. The result will be right-justified in the string you provide. If you use zeroes, this allows you to ignore the NumberLen% spec and just trim the string to the desired length, leaving nothing worse than possible leading zeroes. The length needed by the return string will vary according to the number, with a maximum length depending on the number base chosen. For integers, this will be at most 16 characters (worst case: base 2 or binary). Number$ = STRING$(16, "0") Dec2Any DecimalNr%, NrBase%, Number$, NumberLen% Number$ = RIGHT$(Number$, NumberLen%) DecimalNr integer to convert to another base NrBase% desired number base (2-31) ------- Number$ resulting number in desired base (init >= 16 chars) NumberLen% length of the result (-1 if string too short) Name : Delay (Delay for seconds) Class : Time Level : Clone This routine delays for a given number of seconds. The timing will be the same from an 8088 PC through an 80486 AT-- it's entirely independent of the processor. See also Delay18th. Delay Seconds% Seconds% number of seconds for which to delay Name : Delay18th (Delay for 1/18th seconds) Class : Time Level : Clone This routine delays for a given number of 18ths of seconds. The timing will be the same from an 8088 PC through an 80486 AT-- it's entirely independent of the processor. See also Delay. Delay WaitTime% WaitTime% number of 18ths of seconds for which to delay Name : DelayV (Delay based on Video timing) Class : Time Level : Clone This routine delays for a given number of milliseconds. The timing is based on a signal from the video adapter and may vary somewhat depending on the adapter. The delay is largely independent of the cpu type and speed, however. For anyone unfamiliar with the metric system: there are 1000 milliseconds in one second. Depending on the specific display adapter, this routine may well be fairly inaccurate; it is intended for providing small delays for animation and similar purposes, not as a reliable timer. DelayV MilliSeconds% MilliSeconds% number of milliseconds for which to delay Name : DelChr (Delete Character) Class : Display Level : Clone The DelChr routine deletes the character at the specified screen location. DelChr Row%, Column% Row% row of character Column% column of character Name : DelFile (Delete File) Class : Disk Level : DOS This works like the DOS DEL (or ERASE) command, although it does not allow wildcards. The specified file is deleted. Full path specifications are supported, including drive and subdirectory specs. DelFile FileName$, ErrCode% FileName$ name of the file to delete ------- ErrCode% 0 if no error, else DOS Error Name : DelLine (Delete Line) Class : Display Level : BIOS This routine deletes the specified row from the screen. DelLine Row%, VAttr% Row% row to delete VAttr% color/attr to use on new bottom row (see CalcAttr) Name : DelSub (Delete Subdirectory) Class : Disk Level : DOS This works like the DOS RD (or RMDIR) command. It does not allow wildcards. The specified subdirectory is deleted. Note that you may not delete a subdirectory that you're located in, or a subdirectory which contains files, or the root directory. DelSub SubDir$, ErrCode% SubDir$ name of the subdirectory to delete ------- ErrCode% 0 if no error, else DOS Error Name : DFRead (Direct-to-memory File Read) Class : Disk Level : DOS This routine reads data into an array from a file that was opened by FOpen1 or FCreate. If it wasn't possible to read it all from the file, an error code will be returned and the BytesRead% value will tell you how many bytes were actually read. DFRead Handle%, DSeg%, DOfs%, Bytes%, BytesRead%, ErrCode% Handle% handle of the file from which to read DSeg% segment of the array into which to read the file DOfs% offset of the array into which to read the file Bytes% number of bytes to read ------- BytesWrit% # of bytes actually read from the file (if error) ErrCode% error code: 0 if no error, else DOS Error Name : DFWrite (Direct-from-memory File Write) Class : Disk Level : DOS This routine writes data from an array to a file that was opened by FOpen1 or FCreate. If it wasn't possible to write it all to the file, an error code will be returned and the BytesWrit% value will tell you how many bytes were actually written. DFWrite Handle%, DSeg%, DOfs%, Bytes%, BytesWrit%, ErrCode% Handle% handle of the file to which to write DSeg% segment of the data to write to the file DOfs% offset of the data to write to the file Bytes% number of bytes to write ------- BytesWrit% # of bytes actually written to the file (if error) ErrCode% error code: 0 if no error, else DOS Error Name : DGClear (Direct-to-memory Graphics Clear) Class : Display Level : Any This routine works like the CLS statement, clearing a CGA graphics display. However, rather than clearing the actual screen, DClearSS clears a screen that is stored in an array. This allows you to design a screen in memory, then flash it onto the display using GrafRest. This routine is designed for use with SCREEN 1 or SCREEN 2 (CGA graphics). DGClear DSeg%, DOfs%, Colour% DSeg% segment of the array that holds the screen DOfs% offset of the array that holds the screen Colour% color to use Name : DGetRec (Direct-from-memory Get Record) Class : String Level : Clone The DGetRec routine allows you to get a string from a specified area of memory (numeric array, BIOS data area, display memory, or whatever). The string should be initialized to the desired record length in advance. This works somewhat like an array of fixed length strings or a random file, treating memory as a contiguous series of records of a specified length. DGetRec DSeg%, DOfs%, RecNr%, St$ DSeg% segment of the array to read from DOfs% offset of the array to read from RecNr% record number (starting at 1) ------- St$ returned string. Init to record length (see above). Name : DGetScreen (Direct memory Get Screen image) Class : Display Level : Clone This routine saves any portion of the display to an array. Only text modes are supported. If your program uses multiple display pages, you can get an image from any of those pages. A special "slow" mode is supported for the CGA, to prevent flickering (a problem only with some CGAs). The size of the integer array needed to store a specific area of the screen can be calculated using the CalcSize routine (see). The GetScreen routine works the same way as this, but has a simpler calling convention. Also, if you wish to save the entire screen, you may find ScrSave easier. DGetScreen DSeg%, DOfs%, TRow%, LCol%, BRow%, RCol%, Page%, Fast% DSeg% segment of the array in which to store the image DOfs% offset of the array in which to store the image TRow% top row of the desired screen area LCol% left column of the desired screen area BRow% bottom row of the desired screen area RCol% right column of the desired screen area Page% page from which to get the display area Fast% whether to use fast mode (0 no) Name : DGetSt (Direct-from-memory Get String) Class : String Level : Clone The DGetSt routine allows you to get a string from a specified area of memory (numeric array, BIOS data area, display memory, or whatever). The string should be initialized to the desired length in advance. You may specify an additional offset from the initial location, which itself is specified as a segment and an offset. The second offset begins with position 1. The combined total of the two offsets must be under 65,536 at the moment. I'll remove that restriction at a later time. With normalized segment and offset specifications, which is usually the case, this allows you to specify a number from 1-65,521 for the second offset. DGetSt DSeg%, DOfs%, Posn&, St$ DSeg% segment of the array to read from DOfs% offset of the array to read from Posn& location relative to the start of the array ------- St$ returned string. Init to # of chars desired. Name : DGQPrint (Direct Graphics Quick Print) Class : Display Level : Any This is a simple high-speed replacement for the PRINT statement which works on a CGA virtual graphics screen (SCREEN 2). It does not interpret control codes or support graphics characters (ASCII 128-255). DGQPrint allows you to display to a CGA even if it isn't the active display (use a segment of &HB800 and offset of 0). Its intended use, however, is to display to a virtual screen kept in an array or other memory area. The results can then be displayed using GrafRest. DGQPrint DSeg%, DOfs%, St$, Row%, Column% DSeg% segment of CGA virtual screen DOfs% offset of CGA virtual screen St$ string to display Row% row (1-25) Column% column (1-80) Name : DGXQPrint (Direct Graphics Extended Q Print) Class : Display Level : Any This is a simple high-speed replacement for the PRINT statement which works on a CGA virtual graphics screen (SCREEN 1). It does not interpret control codes or support graphics characters (ASCII 128-255). This routine can also be used on a SCREEN 2 display, where it will display the string in shades instead of in color (using 40 columns/row). DGXQPrint allows you to display to a CGA even if it isn't the active display (use a segment of &HB800 and offset of 0). Its intended use, however, is to display to a virtual screen kept in an array or other memory area. The results can then be displayed using GrafRest. DGXQPrint DSeg%, DOfs%, St$, Row%, Column%, Fore% DSeg% segment of CGA virtual screen DOfs% offset of CGA virtual screen St$ string to display Row% row (1-25) Column% column (1-40) Fore% foreground color (0-3) Name : DGXQPrint1 (Direct Graphics Extended Q Print) Class : Display Level : Any This is a high-speed replacement for the PRINT statement which works on a CGA virtual graphics screen (SCREEN 1). It does not interpret control codes. This routine can also be used on a SCREEN 2 display, where it will display the string in shades instead of in color (using 40 columns/row). DGXQPrint1 allows you to display to a CGA even if it isn't the active display (use a segment of &HB800 and offset of 0). Its intended use, however, is to display to a virtual screen kept in an array or other memory area. The results can then be displayed using GrafRest. DGXQPrint1 DSeg%, DOfs%, St$, Row%, Column%, Fore%, Back% DSeg% segment of CGA virtual screen DOfs% offset of CGA virtual screen St$ string to display Row% row (1-25) Column% column (1-40) Fore% foreground color (0-3) Back% background color (0-3) Name : DInput (Dollar Input) Class : Input Level : Clone This routine provides formatted input of a dollar amount. You specify the format and an initial value (may be zero). You may also specify whether to allow negation-- if so, the user may press the "-" key to toggle the number between negative and positive. The numeric keypad will automatically be locked into the numeric state. Since the decimal point is implicit, the "." key functions as a delete or backspace operation, for convenient one-handed data entry and correction. The dollar amount is kept in a long integer as a number of pennies, to avoid the possibility of round-off errors which might result from use of floating point math. The results are returned to you both as a long integer and as a formatted number. The format string works just like a PRINT USING format string. Editing is not as flexible as for SInput, but is quite adequate. The SInputSet routines will work for DInput as well as SInput. The ExitCode% returned is the same as for SInput, but left and right arrows may also be returned. DInput Format$, St&, St$, MinusOk%, VAttr%, ExitCode% Format$ numeric format (just like PRINT USING format) St& dollar amount (in pennies) MinusOk% whether negation is allowed (0 if no) VAttr% color/attribute to use (see CalcAttr) ------- St& dollar amount (in pennies) St$ formatted dollar amount ExitCode% key used to exit (ASCII code if +, scan code if -) Name : DiskStat (Disk Statistics) Class : Disk Level : DOS DiskStat gives you statistics on the memory usage of a specified disk drive: the total number of clusters, the number of available or free clusters, the number of sectors per cluster, and the number of bytes per sector. From this information, you can determine how much total disk space there is, how much space is left and how much is used, the size of a cluster, et al. A few formulas for you: ClusterSize% = BytesPerSec% * SecsPerClus% FreeSpace& = FreeClus& * ClusterSize% TotalSpace& = TotalClus& * ClusterSize% UsedSpace& = TotalSpace& - FreeSpace& A "cluster" is the minimum amount of disk space that can be allocated at a time. A typical cluster size for a medium-sized hard drive is 2048 bytes, which means that any file from 1-2048 bytes in length is actually taking up a full 2048 bytes on the disk. Large cluster sizes improve file access times but can waste a lot of disk space. DiskStat Drive$, FreeClus&, TotalClus&, BytesPerSec%, SecsPerClus% Drive$ letter of the drive to examine ------- FreeClus& number of free or available clusters TotalClus& total number of clusters BytesPerSec% bytes per sector SecsPerClus% sectors per cluster (-1 if bad drive, etc) Name : Dissolve (Dissolve) Class : Display Level : Clone Like CLS, but a bit more fancy, this routine provides an interesting way to clear the screen. See also FadeOut. This routine may cause heavy flickering on some CGA displays. Dissolve VAttr% VAttr% color/attribute to which to clear (see CalcAttr) Name : DMPrint (DOS Message Print) Class : Display Level : DOS This routine is similar to PRINT, but goes through DOS output services, which allows your program to support output redirection, filters, CTTY and other handy things. See DOSInkey for a DOS input service. Note that the use of DMPrint means that you should avoid using BASIC display handling (CLS, INPUT, LINE INPUT, PRINT, LOCATE, CSRLIN, POS, etc). Instead, you should use ANSI escape sequences to control the display. This requires that an ANSI driver (like ANSI.SYS, DVANSI.SYS, NANSI.SYS, or ZANSI.SYS) be installed on your system. See your DOS manual for details on ANSI sequences, or grab the documentation on ANSI from one of your friendly local BBSes. It is -possible- to use BASIC display handling in conjunction with DMPrint, but that tends to defeat the purpose of using DMPrint in the first place. Note that the DMPrint routine does not add a carriage return/linefeed to the end of a string. If you want that, add CHR$(13) + CHR$(10) to the end of the string. DMPrint St$ St$ string to display Name : DOSClrEol (DOS Clear to End Of Line) Class : Display Level : DOS This routine clears from the cursor position to the end of the row using DOS output functions. It requires that ANSI.SYS or another ANSI driver be installed. DOSClrEol Name : DOSCls (DOS Clear Screen) Class : Display Level : DOS This routine clears the screen using DOS output functions. It requires that ANSI.SYS or another ANSI driver be installed. DOSCls Name : DOSColor (DOS Color) Class : Display Level : DOS This routine sets the screen colors using DOS output functions. It requires that ANSI.SYS or another ANSI driver be installed. DOSColor Fore%, Back% Fore% foreground color Back% background color Name : DOSErrM$ (DOS Error Message) Class : Miscellaneous Level : DOS Of the many PBClone routines that return error codes, most simply pass the code back from DOS without any processing. You can see what the codes mean by checking the chart in PBClone.DOC, or it may be more convenient to use DOSErrM$ instead. This routine returns a short text description of the error in question. ErrMsg$ = DOSErrM$(ErrCode%) ErrCode% error code to translate ------- ErrMsg$ brief explanation of the error Name : DOSInkey (DOS INKEY$) Class : Input Level : DOS This routine is similar to INKEY$, but goes through DOS input services, which allows your program to support input redirection, filters, CTTY and other handy things. See DMPrint for a DOS output service. See also DOSInky$. DOSInkey CharCode%, CharType% ------- CharType% 0 if no key, 1 if normal key, 2 if extended key CharCode% ASCII code if normal key, scan code if extended key Name : DOSInky$ (DOS INKEY$) Class : Input Level : DOS This routine works just like INKEY$, but goes through DOS input services, which allows your program to support input redirection, filters, CTTY and other handy things. See DMPrint for a DOS output service. See also DOSInkey. ky$ = DOSInky$ ------- ky$ key, if any was waiting (0-2 chars/key, like INKEY$) Name : DOSInt% (DOS Interrupt) Class : Miscellaneous Level : DOS This routine provides you with easy access to DOS functions via INT 21H, the major DOS interrupt. It works like the CALL INTERRUPT routines provided with QuickBASIC but is easier to use, at the expense of some flexibility. CAUTION: This routine works directly with DOS, bypassing most of BASIC's safety precautions. Possible chaos may result if you don't know what you're doing! A few specific caveats: 1) Do Not use this routine to exit your program or execute another. BASIC needs to clean up after itself before these tasks, and bypassing its handling is liable to make the system unstable at best. 2) If you expect to use a string or array as a buffer, make sure it is long enough to handle the maximum amount of information anticipated. Strings and arrays can move about in memory, so be sure to get their addresses Just Before using DOSInt%. If you wish to specify BASIC's data segment for DS, you can find out what that is using the DataSeg routine (q.v.). Normally, the CarryFlag% will be set if there is an error, in which case AX will return the error code. CarryFlag% = DOSInt%(AX%, BX%, CX%, DX%, DS%) AX% desired setting of the AX register BX% desired setting of the BX register CX% desired setting of the CX register DX% desired setting of the DX register DS% desired setting of the DS and ES registers ------- AX% returned setting of the AX register BX% returned setting of the BX register CX% returned setting of the CX register DX% returned setting of the DX register DS% returned setting of the DS and ES registers CarryFlag% returned carry flag (0 no error, else code in AX) Name : DOSLocate (DOS Locate) Class : Display Level : DOS This routine sets the cursor position using DOS output functions. It requires that ANSI.SYS or another ANSI driver be installed. Note that many ANSI drivers do not fully support EGA or VGA modes in that they are limited to a maximum of 25 rows. DOSLocate Row%, Column% Row% row Column% column Name : DPutRec (Direct-to-memory Put Record) Class : String Level : Clone The DPutRec routine allows you to put a string into a specified area of memory (numeric array, BIOS data area, display memory, or whatever). The string should be initialized to the desired record length in advance. This works somewhat like an array of fixed length strings or a random file, treating memory as a contiguous series of records of a specified length. DPutRec DSeg%, DOfs%, RecNr%, St$ DSeg% segment of the array to write into DOfs% offset of the array to write into RecNr% record number (starting at 1) St$ string to write. Init to record length (see above). Name : DPutScreen (Direct-from-memory Put Screen) Class : Display Level : Clone This routine restores a portion of the display (which was saved to an array by DGetScreen or GetScreen) to the screen. Only text modes are supported. If your program uses multiple display pages, you can put the image onto any of those pages. A special "slow" mode is supported for the CGA, to prevent flickering (a problem only with some CGAs). The PutScreen routine works the same way as this, but has a simpler calling convention. Also, if you wish to restore the entire screen, you may find ScrRest easier (see). DPutScreen DSeg%, DOfs%, TRow%, LCol%, BRow%, RCol%, Page%, Fast% DSeg% segment of the array from which to restore the image DOfs% offset of the array from which to restore the image TRow% top row of the desired screen area LCol% left column of the desired screen area BRow% bottom row of the desired screen area RCol% right column of the desired screen area Page% page on which to restore the display Fast% whether to use fast mode (0 no) Name : DPutSt (Direct-to-memory Put String) Class : String Level : Clone The DPutSt routine allows you to put a string into a specified area of memory (numeric array, BIOS data area, display memory, or whatever). You may specify an additional offset from the initial location, which itself is specified as a segment and an offset. The second offset begins with position 1. The combined total of the two offsets must be under 65,536 at the moment. I'll remove that restriction at a later time. With normalized segment and offset specifications, which is usually the case, this allows you to specify a number from 1-65,521 for the second offset. DPutSt DSeg%, DOfs%, Posn&, St$ DSeg% segment of the array to write to DOfs% offset of the array to write to Posn& location relative to the start of the array St$ string to write into memory Name : DReadAbs (Disk Read Absolute) Class : Disk Level : DOS This routine reads an absolute disk sector. This is about as low-level as you can get-- the disk is read directly at the byte level, bypassing higher-level notions like filenames and directories. The DReadAbs routine works with any version of DOS, but will not work properly with disk partitions of over 32 megabytes. If you need to work with large disks, see the DReadAbsBig routine. The results from the read will be stored in an array or other memory area you specify. Be sure to make the area large enough to hold everything! A sector is usually 512 bytes, but you can use the DiskStat routine to make sure. Logical sector numbering is used, with sector numbers beginning at zero. DReadAbs Drive$, Sector&, DSeg%, DOfs%, Sectors%, ErrCode% Drive$ drive letter Sector& starting sector (0-65534 [or less on most disks]) DSeg% segment of the array DOfs% offset of the array Sectors% number of sectors to read ------- ErrCode% error code (0 if no error, else DOS error code) Name : DReadAbsBig (Disk Read Absolute, Big) Class : Disk Level : DOS This routine reads an absolute disk sector. This is about as low-level as you can get-- the disk is read directly at the byte level, bypassing higher-level notions like filenames and directories. The DReadAbsBig routine works with DOS 3.31 and later. It will work on disks of any size. If a limit of 32M is sufficient, you might prefer the DReadAbs routine, which works with any DOS version. The results from the read will be stored in an array or other memory area you specify. Be sure to make the area large enough to hold everything! A sector is usually 512 bytes, but you can use the DiskStat routine to make sure. Logical sector numbering is used, with sector numbers beginning at zero. DReadAbsBig Driv$, Sector&, DSeg%, DOfs%, Sectors%, ErrCode% Driv$ drive letter Sector& starting sector (0-65534 [or less on most disks]) DSeg% segment of the array DOfs% offset of the array Sectors% number of sectors to read ------- ErrCode% error code (0 if no error, else DOS error code) Name : DRecDel (Direct-to-memory Record Deletion) Class : Array management Level : Any This routine allows you to delete an item from an array. The item may consist of one or more array elements. The size of the array isn't actually changed, but the array elements are moved as if a deletion took place. DRecDel DSeg%, DOfs%, RecNr%, RecLen%, Records% DSeg% segment of the array DOfs% offset of the array RecNr% record/element number (starting at 1) RecLen% record/element length in bytes Records% total number of records/elements in the array Name : DRecIns (Direct-to-mem Record Insertion) Class : Array management Level : Any This routine allows you to insert an item into an array. The item may consist of one or more array elements. The size of the array isn't actually changed, but the array elements are moved as if an insertion took place. You must of course make sure that the array is DIMed large enough to handle this. DRecIns DSeg%, DOfs%, RecNr%, RecLen%, Records% DSeg% segment of the array DOfs% offset of the array RecNr% record/element number (starting at 1) RecLen% record/element length in bytes Records% total number of records/elements in the array Name : DRecolor (Direct-to-memory Recolor) Class : Display Level : Any The DRecolor routine changes all text in one color to another color. It works only in text modes. The colors are specified as attributes (see CalcAttr). This routine does not necessarily work on the display itself. Instead, it allows you to specify the memory location (segment and offset) of the "screen", which may be an actual screen, a saved screen in an array, a multitasker's virtual screen, etc. Among other things, this makes it easy to work with two displays at once: use a segment of &HB000 for the mono display and &HB800 for the color display (the offset in each case is zero). DRecolor DSeg%, DOfs%, OldAttr%, NewAttr% DSeg% segment of "screen" memory DOfs% offset of "screen" memory OldAttr% color to be changed NewAttr% color to which to change Name : DRecolorArea (Direct-to-memory Recolor Area) Class : Display Level : Clone The DRecolorArea routine changes a specified area of the screen to a specified color. It works only in text modes. The color is specified as an attribute (see CalcAttr). One of the more common applications for this routine is marking an area of the screen, e.g. menu highlight bars. DRecolorArea DSeg%, DOfs%, TRow%, LCol%, BRow%, RCol%, _ VAttr% This routine does not necessarily work on the display itself. Instead, it allows you to specify the memory location (segment and offset) of the "screen", which may be an actual screen, a saved screen in an array, a multitasker's virtual screen, etc. Among other things, this makes it easy to work with two displays at once: use a segment of &HB000 for the mono display and &HB800 for the color display (the offset in each case is zero). DSeg% segment of "screen" memory DOfs% offset of "screen" memory TRow% top row of area to recolor LCol% left column of area to recolor BRow% bottom row of area to recolor RCol% right column of area to recolor VAttr% desired color Name : DriveSpace& (Drive Space free) Class : Disk Level : DOS This routine tells you how many bytes are free on a specified disk drive. BytesFree& = DriveSpace&(Drive$) Drive$ letter of the drive to examine ------- BytesFree& free bytes on the specified drive, or -1 if error Name : DrvSpaceL (Drive Space free as Long integer) Class : Disk Level : DOS This routine tells you how many bytes are free on a specified disk drive. See also DriveSpace, a function-type version of this routine. DrvSpaceL Drive$, BytesFree& Drive$ letter of the drive to examine ------- BytesFree& free bytes on the specified drive, or -1 if error Name : DrvType (Drive Type) Class : Disk Level : DOS 3.1+ The DrvType routine tells you whether a specified drive is fixed or removeable, and whether it is local or remote (network drive). DrvType Drive$, Removeable%, Remote%, ErrCode% Drive$ letter of the drive to examine ------- Removeable% whether the disk can be removed (0 if no) Remote% whether this is a remote drive (0 if no) ErrCode% error code: 0 if none, else bad DOS version Name : DScrRest (Direct-from-mem Screen Restore) Class : Display Level : Clone The DScrRest routine restores a display that was saved using ScrSave or a similar routine. It only works in text modes. See also ScrRest. DScrRest DSeg%, DOfs%, Page%, Fast% DSeg% segment of info to restore to the screen DOfs% offset of info to restore to the screen Page% page on which to restore the display Fast% whether to use fast mode (0 no) Name : DScrSave (Direct-from-memory Screen Save) Class : Display Level : Clone The DScrSave routine saves the display to an array or other storage area. Only text modes are supported. For an 80x25 display, the array must hold 4,000 bytes (4,000 string characters or 2,000 integers). See also ScrSave. DScrSave DSeg%, DOfs%, Page%, Fast% DSeg% segment of place to store the display DOfs% offset of place to store the display Page% page from which to get the display Fast% whether to use fast mode (0 no) Name : DTR (Data Terminal Ready signal) Class : Serial Level : Clone Just as IBM provided the standard for personal computers, Hayes provided the standard for modem commands. Unfortunately, the command method of dropping carrier (hanging up the phone) was badly designed, and all Hayes-compatible modems have a hard time recognizing that command under certain line conditions. Fortunately, there's a more reliable way of hanging up: the DTR serial signal. Turning this signal off will cause the modem to hang up very quickly. Most Hayes-compatible modems are factory-set to pay attention to the DTR; those that aren't can be made to do so either by flipping a hardware switch or with a special initialization command. See your modem manual for details. BASIC will drop the DTR when you CLOSE the comm port, but this isn't always a convenient way to do it. As a matter of fact, this can be a decided nuisance, so many people have patched their version of BASIC to avoid it. If you would like to do so, check your local BBS for the method! With the PBClone DTR routine, you can get full control over the DTR without having to CLOSE the comm port. Note: it may be wise to include a brief delay after dropping the DTR, to give the modem a chance to react. Try Delay18th (see) with a wait of around 4. DTR CommPort%, TurnOn% CommPort% serial port (1-4, though BASIC only handles 1-2) TurnOn% whether to raise (turn on) the DTR (0 if no) Name : DupeVar (Duplicate Variable) Class : Miscellaneous Level : Any This routine allows you to copy the contents of one variable into another, even if the variables are not of the same type. You may specify any variable type EXCEPT variable-length strings: integer, long integer, single, double, fixed-length string, TYPEd variable, etc. Most languages that provide TYPEd variables also provide for variant records, that is, more than one way of looking at the same information. Curiously, BASIC doesn't. This routine allows you to map one variable into another, essentially providing the lacking capability. The only caveat for DupeVar is that both variables must be the same length in bytes. DupeVar FromVar, ToVar FromVar variable from which to copy ------- ToVar variable to which to copy Name : DWindowMan2 (Direct-to-memory Window Manager) Class : Display Level : Any This routine is identical to DWindowManager but for the fact that it allows you to design your own custom window frames. Please see the description of DWindowManager for general information. These are the additional frame types: 6 custom frame composed of a single character 7 custom frame composed of the specified 7-character list: top left corner, top middle, top right corner, left middle, right middle, bottom left corner, bottom middle, bottom right corner /------------------------------------------------------------\ | A custom frame like this would be defined as frame type 7, | | with a frame string of "/-\||\-/", for instance. | \------------------------------------------------------------/ ************************************************* * On the other hand, a frame like this would be * * frame type 6, with a frame string of "*". * ************************************************* Note that this routine differs from the ProBas equivalent in that it supports full frame definitions through frame type 7 (ProBas only supports type 6). The other differences mentioned under WindowManager are also relevant. DWindowMan2 DSeg%, DOfs%, TRow%, LCol%, BRow%, RCol%, Frame%, FSt$, Fore%, Back%, Grow%, Shade%, TFore%, Title$ DSeg% segment of "screen" memory DOfs% offset of "screen" memory TRow% top row of window LCol% left column of window BRow% bottom row of window RCol% right column of window Frame% frame type (see above) FSt$ frame definition string (see above) Fore% frame foreground color Back% frame background color Grow% window growing option (see above) Shade% window shadow option (see above) TFore% title foreground color Title$ window title ("" if none) Name : DWindowMan3 (Direct-to-memory Window Manager) Class : Display Level : Any This routine is identical in function to DWindowManager. The parameters are mostly passed as an array, however, instead of one by one. Please see the description of DWindowManager for general information. DWindowMan3 Parm%(), Title$ DSeg% segment of "screen" memory DOfs% offset of "screen" memory Parm%(1) top row of window Parm%(2) left column of window Parm%(3) bottom row of window Parm%(4) right column of window Parm%(5) frame type (see above) Parm%(6) frame foreground color Parm%(7) frame background color Parm%(8) window growing option (see above) Parm%(9) window shadow option (see above) Parm%(10) title foreground color Title$ window title ("" if none) Name : DWindowMan4 (Direct-to-memory Window Manager) Class : Display Level : Any This is an extremely cut-down version of DWindowManager, providing no more than a simple frame generator. These are the available frame types: 0 no frame 1 single lines 2 double lines 3 single horizontal, double vertical lines 4 double horizontal, single vertical lines 5 block graphic lines Note that this routine is different from its ProBas equivalent in that a new frame type (5) is available. DWindowMan4 DSeg%, DOfs%, TRow%, LCol%, BRow%, RCol%, _ Frame%, VAttr% DSeg% segment of "screen" memory DOfs% offset of "screen" memory TRow% top row of window LCol% left column of window BRow% bottom row of window RCol% right column of window Frame% frame type (see above) VAttr% frame color/attribute (use CalcAttr) Name : DWindowManager (Direct-to-memory Window Manager) Class : Display Level : Any DWindowManager displays a pop-up window according to your specifications. The window may have any of a variety of frames, a title, or a shadow, and it may appear instantly or "grow" onto the screen. These are the available frame types: 0 no frame 1 single lines 2 double lines 3 single horizontal, double vertical lines 4 double horizontal, single vertical lines 5 block graphic lines These are the available shadows: -3 transparent shadow on the right -2 transparent shadow on the left -1 solid black shadow on the left 0 no shadow 1+ shadow attribute (use CalcAttr) for a colored shadow Options for growing windows are as follows: -1 grow as fast as possible 0 pop onto the screen 1+ grow with delay given in milliseconds (15 works for me) Note that this routine is different from its ProBas equivalent in a number of respects. The grow delay time is different. Growing is done more smoothly. The shadow and title parameters are not changed by this routine. A new frame type (5) was added. If a title is too long, it is truncated instead of being ignored completely. Using a -1 as the title foreground color will not turn off the title; instead, use a null title string. DWindowManager DSeg%, DOfs%, TRow%, LCol%, BRow%, RCol%, Frame%, Fore%, Back%, Grow%, Shade%, TFore%, Title$ This routine does not necessarily work on the display itself. Instead, it allows you to specify the memory location (segment and offset) of the "screen", which may be an actual screen, a saved screen in an array, a multitasker's virtual screen, etc. Among other things, this makes it easy to work with two displays at once: use a segment of &HB000 for the mono display and &HB800 for the color display (the offset in each case is zero). DSeg% segment of "screen" memory DOfs% offset of "screen" memory TRow% top row of window LCol% left column of window BRow% bottom row of window RCol% right column of window Frame% frame type (see above) Fore% frame foreground color Back% frame background color Grow% window growing option (see above) Shade% window shadow option (see above) TFore% title foreground color Title$ window title ("" if none) Name : DWriteAbs (Disk Write Absolute) Class : Disk Level : DOS This routine writes an absolute disk sector. This is about as low-level as you can get-- the disk is written directly at the byte level, bypassing higher-level notions like filenames and directories. This is DANGEROUS! If you screw up, DOS may not be able to read the disk any more, and it may need to be reformatted. Back up your data before trying this routine! The DWriteAbs routine works with any version of DOS, but will not work properly with disk partitions of over 32 megabytes. If you need to work with large disks, see the DWriteAbsBig routine. The write will be done from an array or other memory area you specify. Be sure to make the area the right size! A sector is usually 512 bytes, but you can use the DiskStat routine to make sure. Logical sector numbering is used, with sector numbers beginning at zero. DWriteAbs Drive$, Sector&, DSeg%, DOfs%, Sectors%, ErrCode% Drive$ drive letter Sector& starting sector (0-65534 [or less on most disks]) DSeg% segment of the array DOfs% offset of the array Sectors% number of sectors to write ------- ErrCode% error code (0 if no error, else DOS error code) Name : DWriteAbsBig (Disk Write Absolute, Big) Class : Disk Level : DOS This routine writes an absolute disk sector. This is about as low-level as you can get-- the disk is written directly at the byte level, bypassing higher-level notions like filenames and directories. This is DANGEROUS! If you screw up, DOS may not be able to read the disk any more, and it may need to be reformatted. Back up your data before trying this routine! The DWriteAbsBig routine works with DOS 3.31 and later. It will work on disks of any size. If a limit of 32M is sufficient, you might prefer the DWriteAbs routine, which works with any DOS version. The write will be done from an array or other memory area you specify. Be sure to make the area the right size! A sector is usually 512 bytes, but you can use the DiskStat routine to make sure. Logical sector numbering is used, with sector numbers beginning at zero. DWriteAbsBig Drv$, Sector&, DSeg%, DOfs%, Sectors%, ErrCode% Drv$ drive letter Sector& starting sector (0-65534 [or less on most disks]) DSeg% segment of the array DOfs% offset of the array Sectors% number of sectors to write ------- ErrCode% error code (0 if no error, else DOS error code) Name : DXQPrint (Direct Extended Quick Print) Class : Display Level : Any This routine provides a rather crude, but very fast, display capability. It works like the PRINT statement in BASIC, except that it doesn't move the cursor or process control codes. It works only in text modes. This routine does not necessarily work on the display itself. Instead, it allows you to specify the memory location (segment and offset) of the "screen", which may be an actual screen, a saved screen in an array, a multitasker's virtual screen, etc. Among other things, this makes it easy to work with two displays at once: use a segment of &HB000 for the mono display and &HB800 for the color display (the offset in each case is zero). DXQPrint DSeg%, DOfs%, St$, Row%, Column%, VAttr% DSeg% segment of "screen" memory DOfs% offset of "screen" memory St$ string to display Row% starting row Column% starting column VAttr% color/attribute (see CalcAttr) Name : EGARest7 (EGA Restore for SCREEN 7) Class : Display Level : Clone This routine allows you to restore a SCREEN 7 (EGA, 320x200, 16 color) display that was saved using EGASave7 (see). EGARest7 DSeg%, DOfs% DSeg% segment of storage array, returned by VARSEG DOfs% offset of storage array, returned by VARPTR Name : EGARest8 (EGA Restore for SCREEN 8) Class : Display Level : Clone This routine allows you to restore a SCREEN 8 (EGA, 640x200, 16 color) display that was saved using EGASave8 (see). EGARest8 DSeg%, DOfs% DSeg% segment of storage array, returned by VARSEG DOfs% offset of storage array, returned by VARPTR Name : EGARest9 (EGA Restore for SCREEN 9) Class : Display Level : Clone This routine allows you to restore a SCREEN 9 (EGA, 640x350, 16 color) display that was saved using EGASave9 (see). EGARest9 DSeg1%, DOfs1%, DSeg2%, DOfs2% DSeg1% segment of storage array #1, returned by VARSEG DOfs1% offset of storage array #1, returned by VARPTR DSeg2% segment of storage array #2, returned by VARSEG DOfs2% offset of storage array #2, returned by VARPTR Name : EGASave7 (EGA Save for SCREEN 7) Class : Display Level : Clone This routine allows you to save a SCREEN 7 (EGA, 320x200, 16 color) display that can be restored using EGARest7 (see). The array used to hold the screen must contain 32,000 bytes. For an integer array, this means that you must create the array by DIM Array%(1 TO 16000). EGASave7 DSeg%, DOfs% DSeg% segment of storage array, returned by VARSEG DOfs% offset of storage array, returned by VARPTR Name : EGASave8 (EGA Save for SCREEN 8) Class : Display Level : Clone This routine allows you to save a SCREEN 8 (EGA, 640x200, 16 color) display that can be restored using EGARest8 (see). The array used to hold the screen must contain 64,000 bytes. For an integer array, this means that you must create the array by DIM Array%(1 TO 32000). EGASave8 DSeg%, DOfs% DSeg% segment of storage array, returned by VARSEG DOfs% offset of storage array, returned by VARPTR Name : EGASave9 (EGA Save for SCREEN 9) Class : Display Level : Clone This routine allows you to save a SCREEN 9 (EGA, 640x350, 16 color) display that can be restored using EGARest9 (see). Two arrays must be used to hold the screen, for a total of 112,000 bytes. If you use integer arrays, each array must be created by DIM Array%(1 TO 28000). EGASave9 DSeg%, DOfs% DSeg1% segment of storage array #1, returned by VARSEG DOfs1% offset of storage array #1, returned by VARPTR DSeg2% segment of storage array #2, returned by VARSEG DOfs2% offset of storage array #2, returned by VARPTR Name : Elapsed (Elapsed time) Class : Time Level : Any This routine tells you the amount of time elapsed between a given starting time and ending time. The difference between the times must be less than 24 hours for the results to be meaningful. See also ElapsedTime, the FUNCTION version of this routine. Elapsed TimeStart$, TimeStop$, TimeDiff$ TimeStart$ starting time TimeStop$ ending time ------- TimeDiff$ elapsed time Name : ElapsedTime$ (Elapsed time) Class : Time Level : Any This routine tells you the amount of time elapsed between a given starting time and ending time. The difference between the times must be less than 24 hours for the results to be meaningful. See also Elapsed, the SUB version of this routine. TimeDiff$ = ElapsedTime$(TimeStart$, TimeStop$) TimeStart$ starting time TimeStop$ ending time ------- TimeDiff$ elapsed time Name : EMSBuffer (EMS Buffer size) Class : Memory Level : BIOS EMSBuffer tells you how many bytes are needed to save the state of the EMS array routines. Used in conjunction with EMSSave and EMSRest, it allows you to preserve EMS arrays across a CHAIN to another part of your program. EMSBuffer Bytes% EMSState$ = SPACE$(Bytes%) EMSSave EMSState$ ------- Bytes% bytes needed to save EMS array state Name : EMSClose (EMS Close) Class : Memory Level : BIOS The EMSClose routine is used when you are finished with an EMS array. It frees the array handle and EMS memory for other uses. If you don't close all EMS arrays before your program ends, the memory will be lost until the system is rebooted, so it is important to remember EMSClose. EMSClose ArrayHandle% ArrayHandle% handle of an EMS array Name : EMSGet (EMS Get) Class : Memory Level : BIOS This routine gets an element from an EMS array created by EMSOpen. Element numbers start at 0. Be sure to use the right numeric type for the array-- for instance, if you opened the array for SINGLE precision, use "Value!". EMSGet ArrayHandle%, ElementNr&, Value ArrayHandle% handle of an EMS array ElementNr& element number to get ------- Value result (must be correct type for array) Name : EMSOpen (EMS Open) Class : Memory Level : BIOS This routine allows you to open a block of EMS (expanded) memory which can then be accessed like a numeric array. The array size is limited only by available EMS memory (use GetLIMM to find out how much is available). You may specify any numeric type: 1 INTEGER 2 LONG or SINGLE 3 DOUBLE When the array is opened, you are returned an "array handle" which is used to access that array. Access to the array is done via EMSGet and EMSPut. When you are finished with the array, you must close it with EMSClose. As many as 25 EMS arrays can be in use at one time, subject to limitations which may be imposed by your EMS driver (each array requires one EMS handle). EMSOpen Elements&, ElementType%, ArrayHandle%, ErrCode% Elements& number of elements in array (like DIM size) ElementType% numeric type of array (see above) ------- ArrayHandle% handle of an EMS array ErrCode% whether an error occurred (0 no) Name : EMSPut (EMS Put) Class : Memory Level : BIOS This routine puts an element into an EMS array created by EMSOpen. Element numbers start at 0. Be sure to use the right numeric type for the array-- for instance, if you opened the array for SINGLE precision, use "Value!". EMSPut ArrayHandle%, ElementNr&, Value ArrayHandle% handle of an EMS array ElementNr& element number to set Value value to store (must be correct type for array) Name : EMSRest (EMS Restore state) Class : Memory Level : BIOS This routine allows you to restore the state of the EMS array handler. Used in conjunction with EMSBuffer and EMSSave, it allows you to preserve EMS arrays across a CHAIN to another part of your program. EMSRest EMSState$ EMSState$ saved EMS array state Name : EMSSave (EMS Save state) Class : Memory Level : BIOS This routine allows you to save the state of the EMS array handler. Used in conjunction with EMSBuffer and EMSRest, it allows you to preserve EMS arrays across a CHAIN to another part of your program. EMSBuffer Bytes% EMSState$ = SPACE$(Bytes%) EMSSave EMSState$ ------- EMSState$ saved EMS array state Name : EnhKbd (Enhanced Keyboard) Class : Input Level : BIOS By default, the PBClone routines assume an old-style keyboard is in use, for greatest compatibility. EnhKbd allows you to turn on enhanced keyboard handling for the current generation of (usually) 101-key keyboards. This allows access to the F11 and F12 function keys as well as codes for key combinations that used to be ignored, among other things. The KbdType or KbdType2% routine can be used to determine if an enhanced keyboard is available (recommended). Note that EnhKbd works by intercepting the BIOS keyboard handler. All calls to the BIOS keyboard interrupt are converted from the old keyboard functions to the new ones. YOU MUST DISABLE EnhKbd BEFORE YOUR PROGRAM ENDS, so it can restore the old setup. Otherwise, the computer will most probably crash. A list of the new key codes is given in PBClone.DOC. EnhKbd Enable% Enable% turn on enhanced keyboard support (0 disable) Name : Equipment (Equipment information) Class : Equipment Level : BIOS This routine gives you some information about the basic equipment in your computer. Note that the "game port" information is not reliable, due to changes in the meaning of this particular area of the BIOS over many years. Equipment Memory%, Parallel%, Serial%, Game% ------- Memory% kilobytes of conventional memory installed (16 - 640) Parallel% parallel (printer) ports installed (0-4) Serial% serial (communications) ports installed (0-4) Game% game (joystick) ports installed (0-1). See remarks, above. Name : EuropeDate (European Date format) Class : Time Level : Any This routine takes a date in one of the American formats ("MM/DD/YY" or "MM-DD-YYYY") and converts it to the European convention ("DD.MM.YY" or "DD.MM.YYYY"). The date is formatted according to a format string which provides the desired delimiter and year length, e.g. "##-##-##" specifies a delimiter of "-" and a year length of two digits. An error code is returned if the date is not valid. EuropeDate DateSt$, Format$, Result$, ErrCode% DateSt$ date to format (month, day, year order) Format$ format for the date ------- Result$ resulting date (day, month, year order) ErrCode whether the date is valid (0 ok) Name : EWindowManagerC (EGA Window Manager w Char coords) Class : Display Level : Clone EWindowManagerC displays a pop-up window according to your specifications. The window may have any of a variety of frames, a title, or a shadow, and it may appear instantly or "grow" onto the screen. EGA and VGA graphics modes (SCREEN 7 through SCREEN 12) are supported. These are the available frame types: 0 no frame 1 single lines 2 double lines 3 single horizontal, double vertical lines 4 double horizontal, single vertical lines 5 block graphic lines These are the available shadows: 0 no shadow 1+ shadow attribute (use CalcAttr) for a colored shadow Options for growing windows are as follows: -1 grow as fast as possible 0 pop onto the screen 1+ grow with delay given in milliseconds (not recommended) The differences between this routine and its ProBas equivalent are the same as mentioned in the description for WindowManager. In addition, growing windows are supported, but are not recommended (too slow). Colored shadows work as in WindowManager. "True" shadows are not yet supported. EWindowManagerC TRow%, LCol%, BRow%, RCol%, Frame%, Fore%, Back%, Grow%, Shade%, S1%, S2%, TFore%, Title$ TRow% top row of window LCol% left column of window BRow% bottom row of window RCol% right column of window Frame% frame type (see above) Fore% frame foreground color Back% frame background color Grow% window growing option (see above) Shade% window shadow option (see above) S1% unused S2% unused TFore% title foreground color Title$ window title ("" if none) Name : Exist (file Existence) Class : Disk Level : DOS Most versions of BASIC give you no way of seeing if a file exists before you try to OPEN it, so you end up taking your chances. The Exist routine allows you to test to see if the file exists beforehand. It isn't really necessary for the PBClone file routines, which will return an appropriate error code, but it's an important safeguard when using the BASIC OPEN statement. The Exist routine does not support wildcards. If you need that feature, try the FindFirstFx and FindNextFx routines instead. See also Exist2, the FUNCTION version of this routine. Exist FileName$, Found% FileName$ name of the file to look for ------- Found% whether the file was found (0 if no) Name : Exist2% (file Existence) Class : Disk Level : DOS Most versions of BASIC give you no way of seeing if a file exists before you try to OPEN it, so you end up taking your chances. The Exist2% function allows you to test to see if the file exists beforehand. It isn't really necessary for the PBClone file routines, which will return an appropriate error code, but it's an important safeguard when using the OPEN statement. The Exist2% routine does not support wildcards. If you need that feature, try the FindFirstFx and FindNextFx routines instead. See also Exist, the SUB version of this routine. Found% = Exist2%(FileName$) FileName$ name of the file to look for ------- Found% whether the file was found (0 if no) Name : ExplainFAttr$ (Explain File Attribute) Class : Disk Level : Any This function returns a string explaining what a file attribute means, using a specified level of abbreviation. A single space is used between each word, e.g. a hidden subdirectory at abbreviation level 2 would be "Hid Dir". Abbreviation Levels: 1 2 3 --------------------------------------- 1 R R-O Read-Only 2 H Hid Hidden 4 S Sys System 8 V Vol Volume 16 D Dir Directory 32 A Arc Archive This function is convenient in conjunction with any of the routines which return a file attribute: GetAttrF, GetAttrFx, GetFAttr, LoadDirAll. Info$ = ExplainFAttr$(FilAttr%, AbbrevLevel%) We use FilAttr% instead of FileAttr%, since BASIC has a built-in FILEATTR function. FilAttr% file attribute ------- AbbrevLevel% how much to abbreviate the result (1-3) Name : EXQPrintC (EGA Extended Quick Print, Char) Class : Display Level : Clone This routine provides a rather crude, but very fast, display capability. It works like the PRINT statement in BASIC, except that it doesn't move the cursor or process control codes. It works in EGA and VGA graphics modes (SCREEN 7 through SCREEN 12). EXQPrintC St$, Row%, Column%, Fore%, Back% St$ string to display Row% starting row Column% starting column Fore% foreground color Back% background color Name : ExtendFSpec (Extend File Specification) Class : Disk Level : DOS The ExtendFSpec routine combines a number of handy services together. It is intended for processing user-entered file specifications. It does the following: 1) Makes sure the filespec is valid 2) Formats the filespec to normal DOS standards 3) Tells you whether the drive and subdirectories specified exist 4) Fills out any drive or subdirectory information that was left out (optionally includes adding an extension to files which lack one) The error codes returned are as follows: -1 Invalid file specification 0 No error 1 Specified drive does not exist (warning only) 2 Specified subdirectory does not exist (warning only) The ExtendFSpec routine mimics DOS filename handling exactly, to the best of my knowledge. ExtendFSpec File$, Ext$, FullFile$, ErrCode% File$ file specification to process Ext$ extension to add to files that don't have extensions ------- FullFile$ processed file specification ErrCode% error code Name : ExtGet (Extended memory Get) Class : Memory Level : BIOS (AT) This routine allows you to get information from extended memory. It should only be used on AT-class computers, since older PCs do not support extended memory. You may get up to 32,766 words (just under 64 kilobytes) at a time from a specified location in extended memory. The location is specified as the distance from the start of extended memory, starting at 1 for the first location. One word is equivalent to one integer. See ExtMem for information on extended memory constraints. ExtGet DSeg%, DOfs%, Posn&, Words%, ErrCode% DSeg% segment of array to place data from extended memory DOfs% offset of array to place data from extended memory Posn& location of data in extended memory (starting at 1) Words% # of words to transfer (1 int = 1 word = 2 byte) ------- ErrCode% error code (0 if no error) Name : ExtMem (Extended Memory) Class : Memory / Equipment Level : BIOS (AT) This routine allows you to find out how much extended memory is available. It should only be used on AT-class computers, since older PCs do not support extended memory. The amount of memory returned may be either the total amount of extended memory installed or just the amount available at this time, depending on how previously-installed programs (if any) make use of extended memory. Unfortunately, there is no standard which defines how a program should use extended memory as there is with EMS (expanded memory), so there is no way for a program to determine whether or how another program is using extended memory. Microsoft is trying to clear up this situation with its HIMEM driver (available at your local BBS, or [last I looked] free from Microsoft), but this approach hasn't really become standard yet. ExtMem KBytes% ------- KBytes% the number of kilobytes of extended memory Name : ExtPut (Extended memory Put) Class : Memory Level : BIOS (AT) This routine allows you to put information into extended memory. It should only be used on AT-class computers, since older PCs do not support extended memory. You may put up to 32,766 words (just under 64 kilobytes) at a time into a specified location in extended memory. The location is specified as the distance from the start of extended memory, starting at 1 for the first location. One word is equivalent to one integer. Note that you can't rely on extended memory being available just because it exists. There is no automatic way to determine if another program is also trying to use the same extended memory. If in doubt, allow a user-installed option to enable/disable the use of extended memory by your program. ExtPut DSeg%, DOfs%, Posn&, Words%, ErrCode% DSeg% segment of data to store in extended memory DOfs% offset of data to store in extended memory Posn& location to place data in extended memory Words% # of words to transfer (1 int = 1 word = 2 bytes) ------- ErrCode% error code (0 if no error) Name : Extract (Extract delimited substring) Class : String Level : Any Extract allows you to remove any one of a list of delimited substrings in a string. It's useful for input parsing and database work. You pass it the string, delimiter, and the number of the desired substring (numbers start at one). It returns the starting position of the substring within the string and the length of the substring (0 if not found). Just for example, let's assume we have a string as follows: St$ = "Tom Hanlin=3544 E. Southern Ave #104=Mesa, AZ 85204" If we selected a delimiter of "=" and substring number three, the results would be "Mesa, AZ 85204". Delimiters of more than one character are fine. This can be handy for locating carriage return/linefeed pairs, among other things. Extract St$, Delimiter$, SubStrNr%, StartPosn%, SLen% SubSt$ = MID$(St$, StartPosn%, SLen%) St$ string from which to extract Delimiter$ delimiter between substrings SubStrNr% number of the desired substring ------- StartPosn% starting position of substring within the string SLen% length of the substring (0 if none) Name : FadeOut (Fade Out) Class : Display Level : Clone Like CLS, but a bit more fancy, this routine provides an interesting way to clear the screen. See also Dissolve. FadeOut VAttr% VAttr% color/attribute to which to clear (see CalcAttr) Name : FarPeek% (Far memory Peek) Class : Memory Level : Clone This is like the BASIC PEEK function, but expects both a segment and an offset, thus doing away with the need for DEF SEG. This is especially handy for use in subprograms which might otherwise inadvertently change the DEF SEG value expected by the main program. Value% = FarPeek%(DSeg%, DOfs%) Related routines include FarPeekI%, FarPeekL&, DGetSt, DGetRec. DSeg% segment of the location to look at DOfs% offset of the location to look at ------- Value% value at the specified memory location (byte: 0-255) Name : FarPeekI% (Far memory Peek Integer) Class : Memory Level : Clone This is like the BASIC PEEK function, but expects both a segment and an offset, thus doing away with the need for DEF SEG. This is especially handy for use in subprograms which might otherwise inadvertently change the DEF SEG value expected by the main program. Unlike PEEK, this routine returns a word (integer) rather than a byte. Value% = FarPeekI%(DSeg%, DOfs%) Related routines include FarPeek%, FarPeekL&, DGetSt, DGetRec. DSeg% segment of the location to look at DOfs% offset of the location to look at ------- Value% value at the specified memory location (word) Name : FarPeekL& (Far memory Peek Long integer) Class : Memory Level : Clone This is like the BASIC PEEK function, but expects both a segment and an offset, thus doing away with the need for DEF SEG. This is especially handy for use in subprograms which might otherwise inadvertently change the DEF SEG value expected by the main program. Unlike PEEK, this routine returns a dword (long integer) rather than a byte. Value& = FarPeekL&(DSeg%, DOfs%) Related routines include FarPeek%, FarPeekI%, DGetSt, DGetRec. DSeg% segment of the location to look at DOfs% offset of the location to look at ------- Value& value at the specified memory location (dword) Name : FarPoke (Far memory Poke) Class : Memory Level : Clone This is like the BASIC POKE statement, but expects both a segment and an offset, thus doing away with the need for DEF SEG. This is especially handy for use in subprograms which might otherwise inadvertently change the DEF SEG value expected by the main program. FarPoke DSeg%, DOfs%, Value% Related routines include FarPokeI, FarPokeL, DPutSt, DPutRec. DSeg% segment of the location to look at DOfs% offset of the location to look at Value% value to store in the given memory posn (byte: 0-255) Name : FarPokeI (Far memory Poke Integer) Class : Memory Level : Clone This is like the BASIC POKE statement, but expects both a segment and an offset, thus doing away with the need for DEF SEG. This is especially handy for use in subprograms which might otherwise inadvertently change the DEF SEG value expected by the main program. Unlike POKE, this routine stores a word or integer. FarPokeI DSeg%, DOfs%, Value% Related routines include FarPoke, FarPokeL, DPutSt, DPutRec. DSeg% segment of the location to look at DOfs% offset of the location to look at Value% value to store in the given memory posn (word) Name : FarPokeL (Far memory Poke Long integer) Class : Memory Level : Clone This is like the BASIC POKE statement, but expects both a segment and an offset, thus doing away with the need for DEF SEG. This is especially handy for use in subprograms which might otherwise inadvertently change the DEF SEG value expected by the main program. Unlike POKE, this routine stores a dword or long integer. FarPokeL DSeg%, DOfs%, Value& Related routines include FarPoke, FarPokeI, DPutSt, DPutRec. DSeg% segment of the location to look at DOfs% offset of the location to look at Value& value to store in the given memory posn (dword) Name : FClose1 (File Close) Class : Disk Level : DOS This routine closes a file that was opened by FOpen1 or FCreate. It can also be used to close any of the predefined device handles. These are the predefined device handles that are always available: 0 CON stdin standard input, normally the keyboard 1 CON stdout standard output, normally the display 2 CON stderr standard error, almost always display 3 AUX stdaux auxiliary device, generally COM1 4 PRN stdprn standard printer, generally LPT1 If you are running short of handles, you can always close stdaux to free up a handle. The stdprn device can also be closed as long as you don't use the printer or if you only access the printer through LPRINT. It is not a good idea to close stdin, stdout, or stderr under normal circumstances. FClose1 Handle% Handle% handle of the file to close Name : FCreate (File Create) Class : Disk Level : DOS This routine creates a file and opens it for use by the PBClone file handling routines. If the file already existed, it will be wiped out, so you may want to check beforehand if this is a problem. Try the Exist routine. The file is opened in read/write mode, allowing both input and output. You may create the file using any of the following attributes: Normal 0 (nothing special) Read Only 1 file can be read, but not written to Hidden 2 file is "invisible" System 4 special DOS system file The attributes can be combined by adding them together. Don't use the System attribute unless you know what you're doing! Note that this routine does not support file sharing. If that is a problem, close the file just after it is created and reopen it using FOpen1. FCreate FileName$, FAttr%, Handle%, ErrCode% FileName$ name of the file to create FAttr% attribute(s) of the file ------- Handle% handle by which to access the file (if no error) ErrCode% error code: 0 if no error, else DOS Error Name : FDescRead$ (File Description Read) Class : Disk Level : DOS This routine reads a 4DOS-style file description from disk. If there is no description or an error occurs, the result will be a null string. FileDesc$ = FDescRead$(FileName$) FileName$ file name ------- FileDesc$ description of file, if any Name : FGetLoc (File Get Location) Class : Disk Level : DOS This routine tells you the position of the file pointer of a file that was opened using FOpen1 or FCreate. This pointer is used to specify where the next item should be read from or written to the file. The first location of the file is numbered 1. See also FGetLoc2, the FUNCTION version of this routine. FGetLoc Handle%, Posn& Handle% handle of the file ------- Posn& location of the file pointer Name : FGetLoc2& (File Get Location) Class : Disk Level : DOS This routine tells you the position of the file pointer of a file that was opened using FOpen1 or FCreate. This pointer is used to specify where the next item should be read from or written to the file. The first location of the file is numbered 1. See also FGetLoc, the SUB version of this routine. Posn& = FGetLoc2&(Handle%) Handle% handle of the file ------- Posn& location of the file pointer Name : FileCopy (File Copy) Class : Disk Level : DOS This routine copies one or more files, just like the DOS command "COPY". FileCopy works exactly like the DOS COPY command, except it won't append files. You may use wildcards in both source and destination file specifications. In the event of an error, normal DOS error codes are returned, with two exceptions: -2 attempt to copy files over themselves -1 attempt to copy multiple sources to a single dest file See also CopyFile, a simpler routine which doesn't support wildcards. FileCopy SrcFile$, DestFile$, FCount%, ByteCount&, ErrCode% SrcFile$ source file name(s) DestFile$ destination file name(s) ------- FCount% number of files copied ByteCount& number of bytes copied ErrCode% error code (0 if no error) Name : FileCount (File Count) Class : Disk Level : DOS This routine returns the number of files which match a given file specification and attribute. You need to use this routine before LoadDir or LoadDirAll in order to DIM the array to the appropriate size. The attribute can be any of the usual file attributes: 1 Read-Only 2 Hidden 4 System 16 Directory You can combine attributes by adding their values. For instance, to search for hidden directories, you'd use an attribute of 18. By default, DOS returns normal files as well as files which have the specified attributes, so an attribute of 18 would get you normal files, hidden files, directories, and hidden directories. However, FileCount can be made to screen out unwanted files-- just negate the attribute to force only files of that attribute to be counted. For example, an attribute of -18 would return only hidden subdirectories. FileCount FileSpec$, FilAttr%, Count%, ErrCode% We use FilAttr% instead of FileAttr%, since BASIC has a built-in FILEATTR function. FileSpec$ search filename (may contain wildcards) FilAttr% search file attribute ------- Count% number of matching files found ErrCode% error code (0 if no error) Name : FileCRC (File CRC) Class : Disk Level : DOS This routine calculates a 32-bit CRC for a file. This CRC is derived by a formula which takes each character of the file into consideration. It provides a powerful (although not 100% foolproof) way to verify that a file hasn't changed since you last checked. FileCRC FileName$, Result&, ErrCode% FileName$ source file name(s) ------- Result& 32-bit CRC of the file ErrCode% error code (0 if no error) Name : FileMenu (File Menu) Class : Input Level : Clone This routine provides a list of files according to the filespec and attribute you pass it and allows the user to pick a single file from the resulting list. The filespec may contain a full path and wildcards. The attribute may be negated if you insist on an exact match (directories only, for example), or use a normal attribute for multiple matches (directories and files, for instance). Many of the usual WindowManager parameters are used here-- top row, left column, and bottom row (right column is calculated for you), window frame color and frame type, growth, shadow, title string and title color-- see the WindowManager routine for details. For a description of file search attributes, see the FindFirstFx routine. If you allow using the mouse, be sure the mouse is initialized (MMCheck or MMCheck2%) and the mouse cursor is visible (MMCursorOn) before calling this routine. This routine automatically saves and restores the underlying screen. It can handle up to 2,048 files in a window. See CalcAttr if you're not familiar with color/attributes. FileMenu Mouse%, FileSpec$, SeekAttr%, TopRow%, LeftCol%, _ BottomRow%, Frame%, FrameAttr%, FileListAttr%, _ HiliteAttr%, TitleFore%, Title$, Grow%, Shade% Mouse% whether to support the mouse (0 no, -1 yes) FileSpec$ filespec to use in creating the file list SeekAttr% file search attribute to use in creating list TopRow% top row of pick window LeftCol% left column of pick window BottomRow% bottom row of pick window Frame% frame type FrameAttr% frame color/attribute FileListAttr% file list color/attribute HiliteAttr% highlight bar color/attribute TitleFore% title foreground color (backgnd is frame color) Title$ title (use "" for no title) Grow% window growth Shade% window shadow ------- FileSpec$ file picked ("" if none) Name : FindFirstA (Find First file in an Archive) Class : Disk Level : DOS The FindFirstA routine is used to find the first file that matches search parameters which you specify. Various information about the file that matches (if any) can be retrieved by other routines. Rather than working on a directory, this routine works on files in an archive. Supported archive formats include ARC, ARJ, LZH, PAK, ZIP and ZOO, as well as LHARC and PKZIP (ZIP2EXE) self-extracting archives in .COM or .EXE form. If no extension is given, a search will be made through each valid archive extension, and the first matching archive will be used for the file search. Archive names may contain drive and subdirectory specs, but not wildcards. File names may contain wildcards, but not drive or subdir specs. When you are done searching, be sure to use CloseA to terminate the search. Routines in this series include: FindFirstA, FindNextA, GetNameA, GetCRCA, GetCRCAL, GetDateA, GetTimeA, GetSizeAL, GetStoreA FindFirstA ArcName$, FileName$, ErrCode% ArcName$ name of archive to search through FileName$ name of file(s) for which to search ------- ErrCode% error code (0 if no error, else no matching files) Name : FindFirstF (Find First File) Class : Disk Level : DOS This is part of a set of routines included for compatibility with ADVBAS and ProBas. A better solution may be found in FindFirstFx. The FindFirstF routine is used to find the first file that matches search parameters which you specify. Various information about the file that matches (if any) can be retrieved by other routines. See also FindNextF. The file name specified may contain a drive and subdirectory specification. Wildcards are also allowed. Possible search attributes are as follows: Normal 0 (nothing special) Hidden 2 file is "invisible" System 4 special DOS system file Subdirectory 16 subdirectory You can combine the attributes by adding them together. All searches will match if any of the specified attributes are found, so if you're looking only for a specific attribute, you will need to test the results using GetAttrF. Routines in this series include: FindFirstF, FindNextF, GetNameF, GetAttrF, GetDateF, GetTimeF, GetSizeFL FindFirstF FileName$, FAttr%, ErrCode% FileName$ name of file(s) for which to search FAttr% file attribute(s) to seek ------- ErrCode% error code (0 if no error, else no matching files) Name : FindFirstFx (Find First File, Extended) Class : Disk Level : DOS The FindFirstFx routine is used to find the first file that matches search parameters which you specify. Various information about the file that matches (if any) can be retrieved by other routines. The file name specified may contain a drive and subdirectory specification. Wildcards are also allowed. Possible search attributes are as follows: Normal 0 (nothing special) Read Only 1 file can be read, but not written to Hidden 2 file is "invisible" System 4 special DOS system file Subdirectory 16 subdirectory You can combine the attributes by adding them together. All searches will match if any of the specified attributes are found, so if you're looking only for a specific attribute, you will need to test the results using GetAttrFx. Routines in this series include: FindFirstFx, FindNextFx, GetNameFx$, GetAttrFx%, GetDateFx$, GetTimeFx$, GetSizeFx& These routines differ from the older FindFirstF-based series in two major respects. They include a Buffer$ parameter, which allows you to have more than one search going on at a time. This makes it safe to use these routines in subprograms without conflict with the main program. It also allows you to search entire subdirectory trees recursively. The other major difference is that many of these routines are coded as functions for greater convenience. Buffer$ = SPACE$(64) FindFirstFx Buffer$, FileName$, FAttr%, ErrCode% FileName$ name of file(s) for which to search FAttr% file attribute(s) to seek ------- Buffer$ buffer used in search (init to 64 characters) ErrCode% error code (0 if no error, else no matching files) Name : FindNextA (Find Next file in an Archive) Class : Disk Level : DOS This routine is for use after FindFirstA, to find any additional archived files which may match your search specifications. Routines in this series include: FindFirstA, FindNextA, GetNameA, GetCRCA, GetCRCAL, GetDateA, GetTimeA, GetSizeAL, GetStoreA FindNextA ErrCode% ------- ErrCode% error code (0 if no error, else no matching files) Name : FindNextF (Find Next File) Class : Disk Level : DOS This routine is for use after FindFirstF, to find any additional files which may match your search specifications. Routines in this series include: FindFirstF, FindNextF, GetNameF, GetAttrF, GetDateF, GetTimeF, GetSizeFL FindNextF ErrCode% ------- ErrCode% error code (0 if no error, else no matching files) Name : FindNextFx (Find Next File, Extended) Class : Disk Level : DOS This routine is for use after FindFirstFx, to find any additional files which may match your search specifications. Routines in this series include: FindFirstFx, FindNextFx, GetNameFx$, GetAttrFx%, GetDateFx$, GetTimeFx$, GetSizeFx& FindNextFx Buffer$, ErrCode% Buffer$ buffer used in search ------- Buffer$ updated buffer ErrCode% error code (0 if no error, else no matching files) Name : FindPatch (Find Patch location) Class : Disk Level : DOS This is one of a set of routines that allow you to write self-modifying code. Your program can patch DATA statements in itself or in another program, allowing you to save configuration information (for example) without having to create additional data files. In order for this routine to work, you must have a series of DATA statements containing quoted strings of the maximum desired length. The first DATA statement must contain a unique string, as FindPatch will use it to locate the data block. Note that if your program is patching itself, you must READ the unique string rather than assigning it directly, to make sure it's unique. The string must exist at only one place in the program. See the PATCHER.BAS file if you would like clarification. This little demo program, when compiled, will patch itself with whatever you enter on the command line. For instance, if you type PATCHER BANANA, it will store "BANANA" in its DATA statement. PDEMO will not work in the QuickBASIC environment, of course. You must compile it to an .EXE file. You may compile the program using any switches. You may not use the /E (/EXEPACK) switch for LINK, though, as this may alter the program DATA area. Likewise, you must not use compression utilities such as PKLite on the program. Routines in this set include FindPatch, SetPatch, PatchDone. FindPatch FileName$, SearchSt$, ErrCode% FileName$ name of the file to patch SearchSt$ value of the first DATA statement MoveBack% not used ------- ErrCode% whether search worked (0 yes, <0 no, >0 Error) Name : FLock (File Lock) Class : Disk Level : DOS This routine locks any part of a file. It will typically be used for random-access files in circumstances where the file needs to be accessed by multiple programs at the same time. This routine lets you lock just the part of the file you need to access, allowing other programs to work with other parts of the file at the same time. It is best to maintain the lock for the shortest time possible, in case someone else needs the same data. The ideal technique is to lock the area, read what data you need, write any changes, and unlock the area as a single program block. Note that it is IMPORTANT to unlock the locked area before the file is closed and before your program terminates. If the file is not properly unlocked, it may be damaged. See also FUnlock. This routine is used for occasions where you expect multiple accesses to a single file, under networking or multitasking conditions. For less demanding file sharing, it is safer to simply lock the entire file when you open it-- see FOpen. FLock FileHandle%, StartPosn&, Bytes&, ErrCode% FileHandle% file handle StartPosn& starting offset (1 for first position) Bytes& number of bytes to lock ------- ErrCode% error code (0 if no error, else DOS error code) Name : FloorD# (Floor, Double-precision) Class : String Level : Any This function returns the largest integer less than or equal to the number you give it. This is most often used for rounding. Result# = FloorD#(Nr#) Nr# number to process ------- Result# result Name : FloorS! (Floor, Single-precision) Class : String Level : Any This function returns the largest integer less than or equal to the number you give it. This is most often used for rounding. Result! = FloorS!(Nr!) Nr! number to process ------- Result! result Name : Floppies (Floppies installed) Class : Equipment / Disk Level : BIOS The Floppies routine tells you how many floppy drives are installed (0-4). See also Floppies2, a function version of this routine. Floppies Drives% ------- Drives% number of floppy disk drives installed Name : Floppies2% (Floppies installed) Class : Equipment / Disk Level : BIOS The Floppies2 routine tells you how many floppy drives are installed (0-4). Drives% = Floppies2% ------- Drives% number of floppy disk drives installed Name : FloppyType (Floppy drive Type) Class : Equipment / Disk Level : Clone (AT) This routine tells you what kinds of floppy drives are installed, if any. A code is returned for each drive, as follows: 0 no drive 1 5 1/4" 360K 2 5 1/4" 1.2M 3 3 1/2" 720K 4 3 1/2" 1.44M Result codes of 5-7 are available, but not yet defined. One might guess that the 2.88M drive supported by DOS 5.0 will be drive type 5. Note that this routine supports a maximum of only two drives. It is possible for a machine to have up to four drives, but there is not currently any good way to find out about them. FloppyType should only be used on AT-class machines. It will not work on PC/XT computers and may cause unusual results if used on such machines. It will also not work on some of the earliest AT machines, which didn't adhere to the standard CMOS format. FloppyType DriveA%, DriveB% ------- DriveA% drive type of first floppy drive DriveB% drive type of second floppy drive Name : FlushToDisk (Flush file buffers To Disk) Class : Disk Level : DOS This is a "file safety" routine for use with files opened by FOpen1 or FCreate. Files are normally buffered by DOS, which makes file handling faster but creates the danger of losing the file if there is a crash or power outage. By flushing the file to disk, you insure that it is updated to the current moment. Note: this routine will need to temporarily create a new file handle if DOS versions before 4.0 are used. FlushToDisk Handle%, ErrCode% Handle% handle of the file to flush ------- ErrCode% error code: 0 if none, else DOS Error Name : FOpen1 (File Open) Class : Disk Level : DOS This routine opens an existing file for use with the PBClone file handling routines. If you need to create a file that doesn't already exist, use the FCreate routine instead. The file may be opened for reading, writing, or both: 0 Read 1 Write 2 Read/Write You may specify a file sharing mode for use with networks and multitaskers. This will only take effect if the DOS version is 3.0 or later and if the DOS SHARE utility has been executed. Otherwise, it will be ignored. 0 Normal compatibility mode: no file sharing 1 Exclusive no one else may access the file 2 Deny Write no one else may write to the file 3 Deny Read no one else may read from the file 4 Deny None anyone else may read from or write to file Most of the time, "Deny Write" will be appropriate. This allows others to read the file, but not to modify the file on you unexpectedly. See the discussion of predefined device handles at FClose1. FOpen1 FileName$, ReadWrite%, Sharing%, Handle%, ErrCode% FileName$ name of the file to open ReadWrite% whether you want input, output, or both (see above) Sharing% file sharing mode (see above) ------- Handle% handle by which to access the file (if no error) ErrCode% error code: 0 if no error, else DOS Error Name : ForceMatch$ (Force Match of file to wildcard) Class : Disk Level : Any The ForceMatch$ function allows you to mimic DOS commands that operate on source file(s) and destination file(s). It forces a source file name to match a specified pattern (which may contain wildcards), producing an appropriate destination file name. For example, if the source is "TESTNAME.BAS" and the pattern is "?RUE*.*", the result would be "TRUENAME.BAS". Consider the DOS command "COPY *.BAS A:*.BAK". The "*.BAK" part is the desired pattern. The "*.BAS" part specifies which files to copy to the new pattern. Each filename that matches "*.BAS" is translated through the "*.BAK" pattern to give the destination filename. The ForceMatch$ function is designed to do this sort of translation for you. DestFile$ = ForceMatch$(Pattern$, SrcFile$) Pattern$ pattern of desired file name (may contain wildcards) SrcFile$ file name to force through the pattern ------- DestFile$ resulting file name Name : FormatDate (Format Date) Class : Time Level : Any This is a highly flexible date formatting routine. It accepts a date in one of the usual American formats ("03-22-1990", "03/22/90", or even "3/22/90") and converts it according to a format string. This format string allows you to normalize the date, select a new delimiter, choose between two-digit and four-digit years, and even change the order from month/day/year to anything else. An error code will be returned if the date is not valid. The format string can be as simple as "##/##/##", which specifies that the usual month/day/year order be used, with a delimiter of "/" and a two-digit year. If you want to change the date order, you would need a format like "DD.MM.YYYY" instead. For sorting or storage, you might want to convert the date to a plain number, using a format string like "YYYYMMDD". The result could then be converted to a LONG with the BASIC VAL function. FormatDate DateSt$, Format$, Result$, ErrCode% DateSt$ date to format (month, day, year order) Format$ format for the date ------- Result$ resulting date ErrCode whether the date is valid (0 ok) Name : FReadLn (File Read Line) Class : Disk Level : DOS This routine works like LINE INPUT-- it reads in an entire line of text from a file. The Dest$ variable must be set to the desired maximum length beforehand. On return, the number of characters is returned in DLen%, and TooLong% will be set if the Dest$ variable is full and a carriage return/linefeed pair was not (yet?) found. Dest$ = SPACE$(MaxLength%) FReadLn Handle%, Dest$, DLen%, TooLong%, ErrCode% Dest$ = LEFT$(Dest$, DLen%) Handle% handle of the file ------- Dest$ result (init to max length first) DLen% number of characters in result TooLong% zero if we read it all, -1 if CR/LF not found ErrCode% zero if no error, else DOS error code Name : FromPostal$ (From Postal Abbreviation) Class : String Level : Any This function returns the state name corresponding to a given two-letter postal abbreviation. It handles all U.S. postal abbreviations, including states (e.g., "AZ" = "Arizona") and a number of other countries (e.g., "PR" = "Puerto Rico"). A null string ("") is returned if the specified abbreviation is not a valid code. The conversion can also be done the other way around-- see the ToPostal$ function. PlaceName$ = FromPostal$(Abbrev$) Abbrev$ two-letter postal abbreviation ------- PlaceName$ place name corresponding with abbreviation Name : FSetEnd (File Set to End) Class : Disk Level : DOS This moves the file pointer to the end of the file. It is for use with files opened by FOpen1 or FCreate. The usual purpose for this is to append information to an existing file. Note that some text files may have a Control-Z or CHR$(26) on the end. For historical reasons, this character is sometimes used as an "end of file" marker. When dealing with text files, you may want to examine the last character of the file to make sure it isn't a Control-Z. Some of Microsoft's BASIC compilers are among the programs which, unfortunately, put a Control-Z at the end of a file (if you OPEN for OUTPUT). FSetEnd Handle% Handle% handle of the file Name : FSetLoc (File Set Location to byte) Class : Disk Level : DOS This moves the file pointer to a specified position in the file. It is for use with files opened by FOpen1 or FCreate. File positions are considered to start at 1. FSetLoc Handle%, Posn& Handle% handle of the file Posn& location to which to move Name : FSetOfs (File Set location by Offset) Class : Disk Level : DOS This moves the file pointer backwards or forwards in the file. It is for use with files opened by FOpen1 or FCreate. FSetOfs Handle%, Offset& Handle% handle of the file Offset& number of bytes by which to move Name : FSetRec (File Set location to Record) Class : Disk Level : DOS This sets the file pointer to a specific record in the file. It is for use with files opened by FOpen1 or FCreate. This routine provides the same function as FSetLoc, but is a bit more convenient for dealing with files composed of fixed-length records. FSetRec Handle%, RecSize%, RecNr% Handle% handle of the file RecSize% number of bytes per record RecNr% number of record (starting at 1) Name : FSetSize (File Set Size) Class : Disk Level : DOS Many people have asked how to delete information from a file. Well, there's no straightforward way to do it most of the time, but if the record is at the end of the file, you can chop it right off. This routine can also be used to make a file larger, perhaps pre-allocating space that will be used later (for better speed). The file in question must have been opened by FCreate or FOpen1. FSetSize Handle%, Bytes& Handle% handle of the file Bytes& desired file size, in bytes Name : FSize (File get Size) Class : Disk Level : DOS This routine allows you to get the size of a file that was opened by FOpen1 or FCreate. See also FSize2, the FUNCTION version of this routine. FSize Handle%, Bytes& Handle% handle of the file ------- Bytes& file size, in bytes Name : FSize2& (File get Size) Class : Disk Level : DOS This routine allows you to get the size of a file that was opened by FOpen1 or FCreate. See also FSize, the Sub version of this routine. Bytes& = FSize2&(Handle%) Handle% handle of the file ------- Bytes& file size, in bytes Name : FUnlock (File Unlock) Class : Disk Level : DOS This routine unlocks any part of a file. It is used to undo the effects of FLock, which locks any part of a file. It is important to pass the exact same parameters to FUnlock as you did to FLock. See also FLock. Note that it is IMPORTANT to unlock the locked area before the file is closed and before your program terminates. If the file is not properly unlocked, it may be damaged. FUnlock FileHandle%, StartPosn&, Bytes&, ErrCode% FileHandle% file handle StartPosn& starting offset (1 for first position) Bytes& number of bytes to unlock ------- ErrCode% error code (0 if no error, else DOS error code) Name : Get4DOSv (Get 4DOS Version) Class : Equipment Level : DOS The Get4DOSv routine returns the version of 4DOS being used. It returns the results as two integers containing the major and minor version numbers. For instance, 4DOS 4.0 would return a major number of 4, minor 0. If 4DOS is not installed, both version numbers will be zero. If you're not familiar with 4DOS, it's a terrific improved replacement for COMMAND.COM. For more information, write JP Software Inc., P.O. Box 1470, Arlington MA 02174, or call your local BBS. Get4DOSv MajorV%, MinorV% ------- MajorV% major part of the 4DOS version MinorV% minor part of the 4DOS version Name : GetAttrF (Get Attribute of File) Class : Disk Level : DOS The GetAttrF routine returns the attributes of a file matched by FindFirstF or FindNextF. Normal 0 (nothing special) Read Only 1 file can be read, but not written to Hidden 2 file is "invisible" System 4 special DOS system file Subdirectory 16 subdirectory Archive 32 (used by some backup utilities) You can see if a certain value is set using the AND operator: IF FAttr% AND 16 THEN PRINT "Subdirectory" Since the values are all powers of two, the AND operator makes for a convenient way of decoding the results. See also the ExplainFAttr$ function, which decodes the meanings of the attribute for you. Routines in this series include: FindFirstF, FindNextF, GetNameF, GetAttrF, GetDateF, GetTimeF, GetSizeFL GetAttrF FAttr% ------- FAttr% attributes that are set Name : GetAttrFx% (Get Attribute of File, Extended) Class : Disk Level : DOS The GetAttrFx% function returns the attributes of a file matched by FindFirstFx or FindNextFx. Normal 0 (nothing special) Read Only 1 file can be read, but not written to Hidden 2 file is "invisible" System 4 special DOS system file Subdirectory 16 subdirectory Archive 32 (used by some backup utilities) You can see if a certain value is set using the AND operator: IF FAttr% AND 16 THEN PRINT "Subdirectory" Since the values are all powers of two, the AND operator makes for a convenient way of decoding the results. See also the ExplainFAttr$ function, which decodes the meanings of the attribute for you. Routines in this series include: FindFirstFx, FindNextFx, GetNameFx$, GetAttrFx%, GetDateFx$, GetTimeFx$, GetSizeFx& FAttr% = GetAttrFx%(Buffer$) Buffer$ buffer used in search ------- FAttr% file attributes Name : GetColor (Get Color) Class : Display Level : Clone This routine tells you the current default foreground and background colors being used by BASIC. It should be used only in text modes. GetColor Foreground%, Background% ------- Foreground% foreground color Background% background color Name : GetCommAddr (Get Comm Address) Class : Serial Level : Clone This routine allows you to determine the base port address of a serial port. You tell it the COM port number (1-4) and it returns the port address. If there is no port installed, zero will be returned. Note that ports are "supposed" to be assigned sequentially-- in other words, if you find a "zero" port address, there will be no ports after that. This is not necessarily the case, however. Some semi-standard machines may have a COM2 without a COM1, for instance. QuickBASIC gets confused in that case, but it's no problem with my PBClone or BasWiz libraries. Aside from purely informational purposes, this routine can be useful in conjunction with SetCommAddr in manipulating the serial ports. GetCommAddr PortNr%, PortAddr% PortNr% COM port number (1-4) ------- PortAddr% port address Name : GetCRCA (Get CRC of Archive file) Class : Disk / Time Level : DOS GetCRCA returns the 16-bit CRC of an archived file matched by the FindFirstA or FindNextA routines. Since some archives use 32-bit CRCs, you may wish to use the more generic version of this routine, GetCRCAL. Routines in this series include: FindFirstA, FindNextA, GetNameA, GetCRCA, GetCRCAL, GetDateA, GetTimeA, GetSizeAL, GetStoreA GetCRCA CRC16% ------- CRC16% 16-bit CRC Name : GetCRCAL (Get CRC of Archive file as Long) Class : Disk / Time Level : DOS GetCRCAL returns the 32-bit CRC of an archived file matched by the FindFirstA or FindNextA routines. If the archive only has a 16-bit CRC, the result is converted to 32 bits, so this routine works with all archives. Routines in this series include: FindFirstA, FindNextA, GetNameA, GetCRCA, GetCRCAL, GetDateA, GetTimeA, GetSizeAL, GetStoreA GetCRCAL CRC32% ------- CRC32% 32-bit CRC Name : GetCRT (Get CRT) Class : Display / Equipment Level : Clone The GetCRT routine simply tells you whether the current display is capable of handling colors or not. An unsophisticated routine, GetCRT assumes that if the display is an MDA/Hercules, it can't do color, but otherwise it can. See also GetEGA, GetHGA and GetVGA. GetCRT Colour% ------- Colour% whether the display is color (0 if no) Name : GetCRT2% (Get CRT) Class : Display / Equipment Level : Clone The GetCRT2 routine simply tells you whether the current display is capable of handling colors or not. An unsophisticated routine, GetCRT2 assumes that if the display is an MDA/Hercules, it can't do color, but otherwise it can. See also GetEGA, GetHGA and GetVGA. Colour% = GetCRT% ------- Colour% whether the display is color (0 if no) Name : GetDateA (Get Date of Archive file) Class : Disk / Time Level : DOS GetDateA returns the date of a archived file matched by the FindFirstA or FindNextA routines. Routines in this series include: FindFirstA, FindNextA, GetNameA, GetCRCA, GetCRCAL, GetDateA, GetTimeA, GetSizeAL, GetStoreA GetDateA MonthNr%, DayNr%, YearNr% ------- MonthNr% month DayNr% day YearNr% year Name : GetDateAT (Get Date from AT clock) Class : Time Level : BIOS (AT) This routine gets the date from the hardware real-time clock in AT-class computers. Depending on the DOS version, this date may be partially or completely independent of the date kept by DOS in software. DOS always reads the date from the hardware clock when it starts up. However, use of the DATE command in DOS (and the DATE$ function in QuickBASIC) may relate only to the software copy of the date, which is not always guaranteed to be the same as the date in the hardware clock due to certain discrepancies in DOS. GetDateAT MonthNr%, DayNr%, YearNr%, ErrCode% ------- MonthNr% month number (1-12) DayNr% day (1-31) YearNr% year (1980-2079) ErrCode% error code: 0 if no error, else clock has stopped Name : GetDateF (Get Date of File) Class : Disk / Time Level : DOS The GetDateF routine returns the date of a file matched by FindFirstF or FindNextF. Routines in this series include: FindFirstF, FindNextF, GetNameF, GetAttrF, GetDateF, GetTimeF, GetSizeFL GetDateF MonthNr%, DayNr%, YearNr% ------- MonthNr% month DayNr% day YearNr% year Name : GetDateFx$ (Get Date of File, Extended) Class : Disk / Time Level : DOS The GetDateFx$ function returns the date of a file matched by FindFirstFx or FindNextFx. Routines in this series include: FindFirstFx, FindNextFx, GetNameFx$, GetAttrFx%, GetDateFx$, GetTimeFx$, GetSizeFx& FileDate$ = GetDateFx$(Buffer$) Buffer$ buffer used in search ------- FileDate$ date of file (e.g., "02-28-1991") Name : GetDOSv (Get DOS Version) Class : Equipment Level : DOS The GetDOSv routine tells you what version of DOS you're using. It returns the results as two integers containing the major and minor version numbers. For instance, MS-DOS 2.11 would return a major number of 2, minor 11. The OS/2 compatibility box returns version numbers beginning at 10.00. For instance, OS/2 v1.1 returns 10.10 and OS/2 v2.0 returns 20.00. GetDOSv MajorV%, MinorV% ------- MajorV% major part of the DOS version MinorV% minor part of the DOS version Name : GetDrive$ (Get default Drive) Class : Disk Level : DOS This routine tells you the letter of the current default drive. See also GetDrv, the SUB version of this routine. Drive$ = GetDrive$ ------- Drive$ default drive letter. Name : GetDrv (Get default Drive) Class : Disk Level : DOS This routine tells you the letter of the current default drive. See also GetDrive, the FUNCTION version of this routine. Drive$ = "x" GetDrv Drive$ ------- Drive$ default drive letter. Init to at least one character. Name : GetDView (Get DESQview version) Class : Miscellaneous Level : DOS The GetDView routine tells you what version of DESQview is loaded. It returns the results as two integers containing the major and minor version numbers. For instance, DESQview 2.0 would return a major number of 2 and a minor number of 0. If DESQview is not loaded, zeroes are returned. See also GetTView, GetTVScreen, UpdTVScreen. GetDView MajorV%, MinorV% ------- MajorV% major part of the DESQview version (0 if no DESQview) MinorV% minor part of the DESQview version Name : GetEGA (Get EGA information) Class : Display / Equipment Level : BIOS This routine tells you whether an EGA (or VGA) is available, and if so, what kind. It tells you whether the attached display is monochrome or color, and how many kilobytes of RAM are installed in the adapter. Many early EGAs had only 64K of RAM. Current adapters have 256K or more. Since there are some limitations attached to having only 64K, it's a good idea to see if this is the case-- most PBClone EGA routines won't work properly on 64k adapters. See also GetCRT, GetHGA and GetVGA. See also GetEGA2, the FUNCTION version of this routine. GetEGA Display%, KBytes% ------- Display% EGA display type: 0 no EGA, 1 EGA color, 2 EGA mono KBytes% kilobytes of display memory Name : GetEGA2% (Get EGA information) Class : Display / Equipment Level : BIOS This routine tells you whether an EGA (or VGA) is available. See also GetCRT2, GetHGA and GetVGA2. See also GetEGA, the SUB version of this routine. It returns additional information. IsEGA% = GetEGA2% ------- IsEGA% whether the display is an EGA (0 if no) Name : GetError (Get Error code from DOS) Class : Miscellaneous Level : Clone NOTE: The GetError2% function should be used in preference to this routine. The GetError routine is used in conjunction with CatchError. It lets you get the exit code (error level) returned by a program to which you have SHELLed. Since CatchError hooks an interrupt to do its work, you must always make sure to use GetError afterwards to "clean up". See also CatchError. Note that differences in DOS mean that this routine will not always work. In some versions of DOS, you can only get the error level if a batch file was executed; in others, you can't get the error level from a batch file at all. Sorry about that. I don't know of any way to work around it. CatchError SHELL ProgramName$ GetError ExitCode% ------- ExitCode% exit code returned by SHELLed-to program (0-255) Name : GetError2% (Get Error code from DOS) Class : Miscellaneous Level : DOS The GetError2% function gets the exit code (error level) returned by a program to which you have SHELLed. It should be used as soon as possible after the SHELL, and its value will only be meaningful on the first call after the SHELL. This routine should be used in preference to CatchError and GetError. SHELL ProgramName$ ExitCode% = GetError2% ------- ExitCode% exit code returned by SHELLed-to program (0-255) Name : GetExecPath (Get Execution Path of program) Class : Disk Level : DOS 3.0+ This routine returns the full path of your program, i.e., the drive, subdirectory, and name of the program. It does not rely on the current drive and subdirectory settings or look at the PATH setting-- DOS tells it directly. This makes it an excellent way to find the program's "home" directory, where (hopefully) any data files associated with the program will also be stored. SelfName$ = SPACE$(80) GetExecPath SelfName$, SelfLen% SelfName$ = LEFT$(SelfName$, SelfLen%) ------- SelfName$ full path for current program. Init to 80+ chars. SelfLen% length of the full path spec. Name : GetExtM (Get Extended Memory) Class : Memory / Equipment Level : BIOS (AT) This routine allows you to find out how much extended memory is available. It should only be used on AT-class computers, since older PCs do not support extended memory. Note that some of the very early AT machines will return erroneous results. The amount of memory returned may be either the total amount of extended memory installed or just the amount available at this time, depending on how previously-installed programs (if any) make use of extended memory. Unfortunately, there is no standard which defines how a program should use extended memory as there is with EMS (expanded memory), so there is no way for a program to determine whether or how another program is using extended memory. Microsoft is trying to clear up this situation with its HIMEM driver (available at your local BBS, or [last I looked] free from Microsoft), but this approach hasn't really become standard yet. GetExtM KBytes% ------- KBytes% the number of kilobytes of extended memory Name : GetFAttr (Get File Attribute) Class : Disk Level : DOS This routine lets you read the attributes of a file or subdirectory. The attributes may contain a combination of any of the following: Normal 0 (nothing special) Read Only 1 file can be read, but not written to Hidden 2 file is "invisible" System 4 special DOS system file Subdirectory 16 subdirectory Archive 32 (used by some backup utilities) You can see if a certain value is set by using the AND operator: IF FAttr% AND 2 THEN PRINT "Hidden file" Since the values are all powers of two, the AND operator makes for a convenient way of decoding the results. See also the ExplainFAttr$ function, which decodes the meanings of the attribute for you. GetFAttr FileName$, FAttr% FileName$ name of the file (or subdirectory) to examine ------- FAttr% attributes that are set Name : GetFDate (Get File Date) Class : Disk / Time Level : DOS This routine gets the date of a file. GetFDate FileName$, MonthNr%, DayNr%, YearNr% FileName$ name of the file to examine ------- MonthNr% month DayNr% day YearNr% year Name : GetFSize (Get File Size) Class : Disk Level : DOS This function gets the size of a file. FileSize& = GetFSize&(FileName$) FileName$ name of the file to examine ------- FileSize& size of the file, in bytes Name : GetFTime (Get File Time) Class : Disk / Time Level : DOS This routine gets the time of a file. GetFTime FileName$, HourNr%, MinuteNr%, SecondNr% FileName$ name of the file to examine ------- HourNr% hour MinuteNr% minute SecondNr% second (always even, due to DOS storage techniques) Name : GetHGA% (Get Hercules Adapter info) Class : Display / Equipment Level : Clone This routine tells you whether a Hercules-compatible monochrome graphics adapter is in use. See also GetCRT2, GetEGA and GetVGA2. IsHGA% = GetHGA% ------- IsHGA% whether the display is Hercules mono graphics (0 no) Name : GetKbd (Get Keyboard toggles) Class : Input Level : Clone The GetKbd routine allows you to get the state of the four keyboard toggles: Insert, Caps lock, Num lock, and Scroll Lock. GetKbd Insert%, Caps%, Num%, Scrl% ------- Insert% whether "insert" mode is on (0 if no) Caps% whether "caps lock" is on (0 if no) Num% whether "num lock" is on (0 if no) Scrl% whether "scroll lock" is on (0 if no) Name : GetKbd1 (Get Keyboard Shifts) Class : Input Level : Clone The GetKbd1 routine allows you to get the state of the four keyboard shift keys: Left shift, Right shift, Control and Alt. GetKbd1 LShift%, RShift%, Control%, Alt% ------- LShift% whether the left shift key is depressed (0 if no) RShift% whether the right shift key is depressed (0 if no) Control% whether a control key is depressed (0 if no) Alt% whether an alt key is depressed (0 if no) Name : GetKbd2 (Get Keyboard Shifts) Class : Input Level : AT BIOS The GetKbd2 routine allows you to get the state of the six keyboard shift keys on an "enhanced" keyboard: Left shift, Right shift, Left Control, Right Control, Left Alt and Right Alt. Normally, the BIOS only lets you see one key at a time, which can be a barrier when you need more input. This is a particular problem with action games and other real-time applications which have complex input requirements. Due to the special way the BIOS treats shift keys, GetKbd2 can tell if the the various shift keys are pressed simultaneously, allowing more flexibility. GetKbd2 LShift%, RShift%, LCtrl%, RCtrl%, LAlt%, RAlt% ------- LShift% whether the left shift key is depressed (0 if no) RShift% whether the right shift key is depressed (0 if no) LCtrl% whether the left control key is depressed (0 if no) RCtrl% whether the right control key is depressed (0 if no) LAlt% whether the left alt key is depressed (0 if no) RAlt% whether the right alt key is depressed (0 if no) Name : GetKey (Get Key or mouse) Class : Input, Mouse Level : BIOS This routine is kind of an extended version of INPUT$. It waits until a key is available at the keyboard and returns the key pressed. At your option, it can also return if a mouse button is pressed. GetKey Mouse%, ASCIIcode%, ScanCode%, LButton%, RButton% Mouse% whether to check the mouse (0: no) ------- ASCIIcode% ASCII code of the key pressed ScanCode% scan code of the key pressed (0 if none) LButton% whether the left mouse button was pressed RButton% whether the right mouse button was pressed Name : GetKey3 (Get Key or 3-button mouse) Class : Input, Mouse Level : BIOS This routine is kind of an extended version of INPUT$. It waits until a key is available at the keyboard and returns the key pressed. At your option, it can also return if a mouse button is pressed. GetKey3 Mouse%, ASCIIcode%, ScanCode%, LButton%, MButton%, RButton% Mouse% whether to check the mouse (0: no) ------- ASCIIcode% ASCII code of the key pressed ScanCode% scan code of the key pressed (0 if none) LButton% whether the left mouse button is pressed MButton% whether the middle mouse button is pressed RButton% whether the right mouse button is pressed Name : GetLabel (Get disk volume Label) Class : Disk Level : DOS This routine gets the volume label from a specified drive. See also GetLabel2$. Label$ = SPACE$(11) GetLabel Drive$, Label$, LabelLen%, ErrCode% Label$ = LEFT$(Label$, LabelLen%) Drive$ letter of the drive to examine ------- Label$ volume label of drive. Init to >= 11 chars. LabelLen% length of the volume label ErrCode% error code: 0 if no error, else DOS Error Name : GetLabel2$ (Get disk volume Label) Class : Disk Level : DOS This routine gets the volume label from a specified drive. See also GetLabel, a subprogram version of this routine. The GetLabel subprogram is preferable in that it returns an error code, but you may find the function version more convenient if error checking is not desired. Label$ = GetLabel2$(Drive$) Drive$ letter of the drive to examine ------- Label$ volume label of the specified drive. Name : GetLIMHandles (Get L/I/M expanded mem Handles) Class : Memory Level : DOS Early Lotus/Intel/Microsoft expanded memory revisions provided a limited number of "handles" which could be used to access expanded memory-- often as few as 15 or so. If your program uses expanded memory and the EMS driver is one of the older versions, you may want to make sure that enough handles are available. This routine tells you how many handles are in use. Note that this routine expects an EMS driver to be installed. If you can't be sure of that, use GetLIMM first to avoid an unpleasant surprise. GetLIMHandles Handles% ------- Handles% number of EMS handles in use Name : GetLIMM (Get L/I/M expanded Memory) Class : Memory / Equipment Level : DOS This routine tells you how much expanded memory is installed. If there is none, or if the EMS driver hasn't been installed, it returns zeroes. You should use this routine before any other of the PBClone routines that access expanded memory, since the other routines expect EMS to be available. The results are returned in terms of EMS pages. Each page is 16 kilobytes. GetLIMM TotalPages%, FreePages% ------- TotalPages% number of EMS pages installed FreePages% number of EMS pages available for use Name : GetLIMV (Get L/I/M expanded mem Version) Class : Memory / Equipment Level : DOS The GetLIMV routine tells you the version of EMS driver that is being used. The version number is separated into major and minor parts. For example, an EMS 3.1 driver would return a major number of 3 and minor number of 1. Note that this routine expects an EMS driver to be installed. If you can't be sure of that, use GetLIMM first to avoid an unpleasant surprise. GetLIMV MajorVer%, MinorVer% ------- MajorVer% major part of the EMS version number MinorVer% minor part of the EMS version number Name : GetLine (Get Line of text) Class : Display Level : Any This routine retrieves a row of text from a saved (or virtual) screen. You can use GetLine with a saved screen of any size. The St$ parameter must be initialized to the width of the saved screen (in columns). See also ReadScreen, which allows you to read a string of any length directly from the display. St$ = SPACE$(ScrWidth%) ' init to v. screen width GetLine DSeg%, DOfs%, Row%, St$, SLen% St$ = LEFT$(St$, SLen%) DSeg% segment of saved screen DOfs% offset of saved screen Row% row of saved screen (starting at 1) ------- St$ text at given row (init to width of saved screen) SLen logical length of text Name : GetMemBox (Get Memory Box info) Class : Memory Level : DOS The PBClone library comes with a TSR called MEMBOX.COM. This TSR reserves an area of memory which can be used as a transfer area for communication between multiple programs-- the data remains as long as the TSR is installed. The GetMemBox routine tells you whether MEMBOX is installed, how much memory it has, and the location of that memory. You can access the MEMBOX memory using any PBClone routine that accepts segment and offset pointers. The DGetSt and DPutSt routines will probably be most helpful for general use. NOTE that MEMBOX expects to be the last TSR installed. If any other TSR or program alters the INT 2Fh interrupt vector while MEMBOX is active, the results are liable to be messy at best. GetMemLoc DSeg%, DOfs%, Bytes% ------- DSeg% memory segment DOfs% memory offset Bytes% bytes available (0 if MEMBOX is not installed) Name : GetMouseLoc (Get Mouse Location) Class : Mouse Level : BIOS This routine allows you to get the current location of the mouse cursor. It doesn't matter if the cursor is visible or invisible. GetMouseLoc is only for use in text mode. This routine will not work properly if there is no mouse available. Use the MMCheck routine if you are not sure. See also MMGetLoc, which returns the coordinates for graphics mode. GetMouseLoc Row%, Column% ------- Row% mouse cursor row Column% mouse cursor column Name : GetMouseVer (Get Mouse driver Version) Class : Mouse Level : BIOS This routine retrieves various information about the mouse, including the driver version number, mouse type, and IRQ used by the mouse. Note that this is among the mouse routines that makes you wonder what Microsoft was thinking when they designed the mouse driver. The mouse driver has no provision for error codes and the "get version" function was added comparatively recently, so there is no way of knowing with certainty whether this routine worked or what the mouse driver version is. If that could be a problem, you can reduce the risk by checking the returned values to make sure they appear reasonable. This routine will not work properly if there is no mouse available. Use the MMCheck routine if you are not sure. The mouse type may be any of the following: 1 bus mouse 2 serial mouse 3 InPort mouse 4 PS/2 mouse 5 Hewlett-Packard mouse The IRQ will be 0 on the PS/2. Otherwise, it will be 2-5 or 7 on Microsoft mice. A mouse designed to take advantage of the AT interrupt controller may use higher IRQs (to perhaps 15, I'm not sure), so be generous if you do range checking here. The version number is divided into two parts. For instance, mouse driver 8.20 would return a major version number of 8 and a minor version number of 20. GetMouseVer MajorV%, MinorV%, MType%, IRQ% ------- MajorV% mouse driver major version number MinorV% mouse driver minor version number MType% mouse type IRQ% IRQ used by mouse Name : GetNameA (Get Name of file in Archive) Class : Disk Level : DOS GetNameA returns the name of an archived file matched by the FindFirstA or FindNextA routines. Since some archives may include subdirectory specs along with the file name, it is recommended that you initialize the return string to 80 characters (at least 12 are required). When parsing filenames which may contain subdirectory specs, keep in mind that the forward slash "/" may be used instead of the backslash "\" for delimiting subdirectories. In order to reach the very widest audience, you may also wish to take into account filenames which may have originated on non-PC systems. In such filenames, the length of any part of the path will not necessarily be restricted to the 11-plus-dot of MS-DOS, the dot character may not mean anything special, uppercase/lowercase distinctions may be significant, and characters may be present which are not valid in MS-DOS names. Routines in this series include: FindFirstA, FindNextA, GetNameA, GetCRCA, GetCRCAL, GetDateA, GetTimeA, GetSizeAL, GetStoreA FileName$ = SPACE$(80) GetNameA FileName$, NameLen% FileName$ = LEFT$(FileName$, NameLen%) ------- FileName$ file name (init to >= 12 characters, preferably 80) NameLen% length of file name Name : GetNameF (Get Name of File) Class : Disk Level : DOS The GetNameF routine returns the name of a file matched by FindFirstF or FindNextF. The name will not contain a drive or subdirectory specification. Routines in this series include: FindFirstF, FindNextF, GetNameF, GetAttrF, GetDateF, GetTimeF, GetSizeFL FileName$ = SPACE$(12) GetNameF FileName$, NameLen% FileName$ = LEFT$(FileName$, NameLen%) ------- FileName$ file name (init to at least 12 characters) NameLen% length of file name Name : GetNameFx$ (Get Name of File, Extended) Class : Disk Level : DOS The GetNameFx$ function returns the name of a file matched by FindFirstFx or FindNextFx. The name will not contain a drive or subdirectory specification. Routines in this series include: FindFirstFx, FindNextFx, GetNameFx$, GetAttrFx%, GetDateFx$, GetTimeFx$, GetSizeFx& FileName$ = GetNameFx$(Buffer$) Buffer$ buffer used in search ------- FileName$ file name Name : GetPrtAddr (Get Printer Address) Class : Printer Level : Clone This routine allows you to determine the base port address of a parallel port. You tell it the LPT port number (1-4) and it returns the port address. If there is no port installed, zero will be returned. Note that up to four printer ports are (theoretically) supported on most machines. On PS/2 computers, only three ports are allowed, and the fourth port data area is used for other purposes. So, it would probably be a good idea to restrict your program to ports 1-3. Aside from purely informational purposes, this routine can be useful in conjunction with SetPrtAddr in manipulating the parallel ports. GetPrtAddr PortNr%, PortAddr% PortNr% LPT port number (1-4 or 1-3 [see above]) ------- PortAddr% port address Name : GetPrtSc% (Get PrtSc press) Class : Input Level : BIOS This function only works when the "print screen" key is disabled, which you can accomplish via the PrtSc routine. It returns whether the print screen key was pressed since you last checked. Like INKEY$, it clears the value after you read it. Pressed% = GetPrtSc% ------- Pressed% whether the print screen key was pressed (0 if no) Name : GetPSP% (Get Program Segment Prefix) Class : Memory Level : DOS This function returns the segment of the Program Segment Prefix, which is a sort of header at the beginning of every program that contains assorted information. You can find out more about the PSP in any DOS technical reference. PSeg% = GetPSP% ------- PSeg% segment of the Program Segment Prefix Name : GetRows (Get Rows on screen) Class : Display Level : Clone This routine tells you how many rows are on the display. This is normally 25, but it may be greater on an EGA or VGA. Only text modes are supported. GetRows Rows% ------- Rows% text rows on the display Name : GetRows2% (Get Rows on screen) Class : Display Level : Clone This routine tells you how many rows are on the display. This is normally 25, but it may be greater on an EGA or VGA. Only text modes are supported. Rows% = GetRows2% ------- Rows% text rows on the display Name : GetScreen (Get Screen) Class : Display Level : Clone This routine saves any portion of the display to an array. Only text modes are supported. If your program uses multiple display pages, you can get an image from any of those pages. A special "slow" mode is supported for the CGA, to prevent flickering (a problem only with some CGAs). The size of the integer array needed to store a specific area of the screen can be calculated using the CalcSize routine (see). If you wish to save the entire screen, you may find ScrSave easier (see). GetScreen Array%(), TRow%, LCol%, BRow%, RCol%, Page%, Fast% TRow% top row of the desired screen area LCol% left column of the desired screen area BRow% bottom row of the desired screen area RCol% right column of the desired screen area Page% page from which to get the display area Fast% whether to use fast mode (0 no) ------- Array%() stored image of the selected area of the screen Name : GetSerial$ (Get disk Serial number) Class : Disk Level : DOS 4.0+ The GetSerial function returns the serial number of the specified disk. If there is no serial number, it returns "0000-0000". SerialNr$ = GetSerial$(Drive$) Drive$ drive to get serial # from ("" for current drive) ------- SerialNr$ serial number of the specified drive Name : GetSizeAL (Get Size of file in Archive Long) Class : Disk Level : DOS GetSizeAL returns the size of an archived file matched by the FindFirstA or FindNextA routines. Routines in this series include: FindFirstA, FindNextA, GetNameA, GetCRCA, GetCRCAL, GetDateA, GetTimeA, GetSizeAL, GetStoreA GetSizeAL OrigSize&, CurrSize& ------- OrigSize& original (uncompressed) file size CurrSize& current (compressed) file size Name : GetSizeFL (Get Size of File as Long) Class : Disk Level : DOS The GetSizeFL routine returns the size of a file matched by FindFirstF or FindNextF. Routines in this series include: FindFirstF, FindNextF, GetNameF, GetAttrF, GetDateF, GetTimeF, GetSizeFL GetSizeFL FileSize& ------- FileSize& file size Name : GetSizeFx& (Get Size of File, Extended) Class : Disk Level : DOS The GetSizeFx& function returns the size of a file matched by FindFirstFx or FindNextFx. Routines in this series include: FindFirstFx, FindNextFx, GetNameFx$, GetAttrFx%, GetDateFx$, GetTimeFx$, GetSizeFx& FileSize& = GetSizeFx&(Buffer$) Buffer$ buffer used in search ------- FileSize& file size Name : GetStoreA (Get Storage of file in Archive) Class : Disk / Time Level : DOS GetStoreA returns the method used to compress an archived file matched by the FindFirstA or FindNextA routines. Routines in this series include: FindFirstA, FindNextA, GetNameA, GetCRCA, GetCRCAL, GetDateA, GetTimeA, GetSizeAL, GetStoreA Storage$ = SPACE$(8) GetStoreA Storage$ ------- Storage$ storage method (init to 8 characters) Name : GetSub (Get default Subdirectory) Class : Disk Level : DOS The GetSub routine gets the current subdirectory on the default drive. It does not put a backslash at the start of the subdirectory, so you should add this yourself. See also GetSub1, which is a more advanced version of this routine. SubDir$ = SPACE$(64) GetSub SubDir$, SubLen% SubDir$ = "\" + LEFT$(SubDir$, SubLen%) ------- SubDir$ name of the current subdirectory. Init to 64+ chars SubLen% length of the subdirectory name Name : GetSub1 (Get default Subdirectory) Class : Disk Level : DOS The GetSub1 routine gets the current subdirectory on a specified drive. Unlike GetSub, it places a backslash at the start of the name. It also returns an error code, which allows you to see if there was a disk error. If you don't care about the error code, you may prefer GetSub2, the FUNCTION version of this routine. SubDir$ = SPACE$(65) GetSub1 Drive$, SubDir$, SubLen%, ErrCode% SubDir$ = LEFT$(SubDir$, SubLen%) Drive$ letter of the drive to check ------- SubDir$ name of the current subdirectory. Init to 65+ chars SubLen% length of the subdirectory name ErrCode% error code: 0 if no error, else DOS Error Name : GetSub2$ (Get default Subdirectory) Class : Disk Level : DOS The GetSub2 routine gets the current subdirectory on a specified drive. Unlike GetSub, it places a backslash at the start of the name. See also GetSub1, the SUB version of this routine. It returns an error code. If you just want the subdirectory of the current drive, you can use a null string ("") as the drive letter. SubDir$ = GetSub2$(Drive$) Drive$ letter of the drive to check ------- SubDir$ name of the current subdirectory. Init to 65+ chars Name : GetSwitch (Get Switch character) Class : Miscellaneous Level : DOS An undocumented capability in many DOS versions allows you to set the DOS "switch character", which is the delimiter used to identify a switch on the DOS command line. This is normally a slash, as in "DIR /W". However, many people prefer to change it to a "-", which is the switch character used by Unix. With the normal "/" delimiter, a backslash "\" is used in subdirectory specifications. DOS itself will recognize either one as a subdirectory delimiter, but the command line won't unless the switch char was changed. The upshot of all this is, whereas you might normally use a command like: DIR /W C:\GAMES Someone with a different switch character might use something like this: DIR -W C:/GAMES This is exactly the sort of syntax that Unix commands use. If you design your program to recognize the different delimiters, you will make some people very happy! The GetSwitch routine will detect changed delimiters on those versions of DOS which support it, and will return an ordinary "/" on those versions of DOS which don't. Switch$ = "x" GetSwitch Switch$ ------- Switch$ the DOS switch character. Init to one character. Name : GetSwitch2$ (Get Switch character) Class : Miscellaneous Level : DOS This does exactly the same thing as the GetSwitch routine, but it is a FUNCTION rather than a SUB. For more information, see GetSwitch. Switch$ = GetSwitch2$ ------- Switch$ the DOS switch character Name : GetTick& (Get Tick) Class : Time Level : Clone This function returns the system time. This value represents the time after midnight. There are about 18.2 ticks per second, providing sufficiently fine resolution for most purposes. If you use this function as part of a delay loop, keep in mind that the value will wrap around at midnight, and that any given value may be "skipped" due to causes beyond your control-- multitasking or background operations such as communications or print spooling, for example. So, DO NOT check for a specific "end time"-- it may never come! Instead, decrement a counter whenever you notice that the time has changed since you last checked. This disassociates the delay from a specific time, preventing lockups. Tick& = GetTick& ------- Tick& time after midnight (1/18.2 seconds) Name : GetTime (Get Time) Class : Time Level : DOS This routine tells you the time according to DOS. The main difference between getting the time from BASIC and getting it from DOS is the "hundredths of seconds" value. However, this value is not available on some machines, in which case it will be set to zero. It is not accurate on most machines, being calculated instead using a semi-random approach; it is more of a novelty than a useful value. GetTime HourNr%, MinuteNr%, SecondNr%, Hundredth% ------- HourNr% hour (0-23) MinuteNr% minute SecondNr% second Hundredth% hundredth of a second. See remarks, above. Name : GetTimeA (Get Time of file in Archive) Class : Disk / Time Level : DOS GetTimeA returns the time of an archived file matched by the FindFirstA or FindNextA routines. Routines in this series include: FindFirstA, FindNextA, GetNameA, GetCRCA, GetCRCAL, GetDateA, GetTimeA, GetSizeAL, GetStoreA GetTimeA HourNr%, MinuteNr%, SecondNr% ------- HourNr% hour MinuteNr% minute SecondNr% second Name : GetTimeAT (Get Time from AT clock) Class : Time Level : BIOS (AT) This routine gets the time from the hardware real-time clock in AT-class computers. Depending on the DOS version, this time may be partially or completely independent of the time kept by DOS in software. DOS always reads the time from the hardware clock when it starts up. However, use of the TIME command in DOS (and the TIME$ function in QuickBASIC) may relate only to the software copy of the time, which is not always guaranteed to be the same as the time in the hardware clock due to certain discrepancies in DOS. GetTimeAT HourNr%, MinuteNr%, SecondNr%, ErrCode% ------- HourNr% hour (0-23) MinuteNr% minute SecondNr% second ErrCode% error code: 0 if no error, else clock has stopped Name : GetTimeF (Get Time of File) Class : Disk / Time Level : DOS The GetTimeF routine returns the time of a file matched by FindFirstF or FindNextF. Routines in this series include: FindFirstF, FindNextF, GetNameF, GetAttrF, GetDateF, GetTimeF, GetSizeFL GetTimeF HourNr%, MinuteNr%, SecondNr% ------- HourNr% hour MinuteNr% minute SecondNr% second Name : GetTimeFx$ (Get Time of File, Extended) Class : Disk / Time Level : DOS The GetTimeFx$ function returns the time of a file matched by FindFirstFx or FindNextFx. Routines in this series include: FindFirstFx, FindNextFx, GetNameFx$, GetAttrFx%, GetDateFx$, GetTimeFx$, GetSizeFx& FileTime$ = GetTimeFx$(Buffer$) Buffer$ buffer used in search ------- FileTime$ file time (e.g., "17:53:20") Name : GetTView (Get TopView) Class : Miscellaneous Level : BIOS This routine tells you whether TopView or a compatible multitasker (such as TaskView or DESQview) is loaded. See also GetDView, GetTVScreen, UpdTVScreen. GetTView Installed% ------- Installed% whether a TopView-type multitasker is loaded Name : GetTVScreen (Get TopView Screen address) Class : Display / Miscellaneous Level : BIOS GetTVScreen returns the address of the screen buffer used by a TopView-type multitasker. This allows you to use direct screen access while remaining within the windows allocated to your program by the multitasker. You must tell the multitasker the address of the screen you would be writing to if the multitasker was not installed. Specify a segment of &HB000 if using an MDA or Hercules, or a segment of &HB800 for CGA, EGA, MCGA or VGA. The offset should always be 0. This is for use in text modes. The routine will return with the new segment and offset for you to use. These values can be used with any PBClone screen routine that accepts a segment and offset-- DQPrint and DXQPrint, for example. Note that not all TopView-compatible multitaskers will automatically update the screen from the buffer. The UpdTVScreen routine allows you to force a screen update. See also GetDView, GetTView, UpdTVScreen. GetTVScreen DSeg%, DOfs% DSeg% segment of desired screen DOfs% offset of desired screen ------- DSeg% segment of screen buffer DOfs% offset of screen buffer Name : GetValidKey (Get Valid Key) Class : Input Level : DOS This one is useful for getting one of a list of keys from the keyboard. You give it a list of keys (letters should be uppercase) to accept. It will wait until one of the listed keys is pressed; for letters, it will accept either lowercase or uppercase keys, but will convert the letter to uppercase before it returns to you. If you pass it a blank list, it will accept any key. This routine is handy for when you want to allow one of a list of choices from a menu, for instance. GetValidKey GoodList$, Result$ GoodList$ list of acceptable keys. See above for remarks. ------- Result$ the key that was accepted (uppercase if letter) Name : GetVerify (Get Verify setting) Class : Disk Level : DOS The GetVerify routine tells you the state of the DOS VERIFY flag. When VERIFY is on, some checking is done to make sure that writing to the disk works as requested. The checks are not very good, however, and VERIFY slows down disk handling, so it is usually better to have VERIFY off. You can change the state of VERIFY by using the DOS VERIFY command or with the SetVerify routine in PBClone. GetVerify VerifyOn% ------- VerifyOn% whether VERIFY is on (0 if no) Name : GetVGA (Get VGA information) Class : Display / Equipment Level : BIOS This routine tells you whether a VGA is available. See also GetCRT, GetEGA and GetHGA. GetVGA IsVGA% ------- IsVGA% whether a VGA is installed (0 if no) Name : GetVGA2% (Get VGA information) Class : Display / Equipment Level : BIOS This routine tells you whether a VGA is available. See also GetCRT, GetEGA and GetHGA. IsVGA% = GetVGA2% ------- IsVGA% whether a VGA is installed (0 if no) Name : GetVGAColor (Get VGA Color) Class : Display Level : BIOS This routine gets the components of a single VGA palette color. It returns the color value associated with a given color number. If you are dealing with more than one color at a time, you may find GetVGAPalette more appropriate. GetVGAColor ColorNr%, Red%, Green%, Blue% ColorNr% color number (1-16 or 1-255, depending on VGA mode) ------- Red% red intensity (0-63) Green% green intensity (0-63) Blue% blue intensity (0-63) Name : GetVGAPalette (Get VGA Palette) Class : Display Level : BIOS This routine allows you to get any number of the VGA palette settings into a TYPEd array. The TYPE for the array should be defined like this: TYPE Palet IRed AS STRING * 1 IBlue AS STRING * 1 IGreen AS STRING * 1 END TYPE This type holds a CHR$-encoded representation of the intensity of each component of the color. The values range from 0-63. If you are only dealing with a few colors, you may find it more convenient to use GetVGAColor instead. GetVGAPalette DSeg%, DOfs%, Start%, Colors% DSeg% segment of the palette array DOfs% offset of the palette array Start% color number to start with Colors% number of colors to get Name : GetVidMode (Get Video Mode) Class : Display Level : BIOS The GetVidMode routine tells you about the current display status from the BIOS' point of view. Note that the BIOS display mode is not the same as the BASIC SCREEN mode (a direct translation between the two is messy, because BASIC conglomerates several BIOS modes into a single SCREEN mode in several instances). GetVidMode BIOSMode%, ScreenWidth%, ActivePage% ------- BIOSMode% BIOS video mode ScreenWidth% number of columns per row ActivePage% active (visible) display page Name : GetXMSm (Get XMS Memory) Class : Memory / Equipment Level : DOS This routine tells you how much XMS memory is available. If there is none, or if the XMS driver hasn't been installed, it returns zeroes. Memory is returned kilobytes. GetXMSm LargestFree&, TotalFree& ------- LargestFree& largest free block of XMS memory TotalFree& total free XMS memory Name : GetXMSv (Get XMS Version) Class : Memory / Equipment Level : BIOS The GetXMSv routine tells you the version of XMS driver that is being used. The version number is separated into major and minor parts. For example, an XMS 2.0 driver would return a major number of 2 and minor number of 0. GetXMSv MajorVer%, MinorVer% ------- MajorVer% major part of the XMS version number MinorVer% minor part of the XMS version number Name : GLoad (Graphics Load) Class : Disk Level : DOS A replacement for the BASIC BLOAD statement, this routine loads a binary memory image from a file into the area of memory it formerly occupied. This is most often used to restore a screen display from a file, although PBClone offers more flexible alternatives. GLoad FileName$ FileName$ name of the file to load into memory Name : GQPrint (Graphics Quick Print) Class : Display Level : Clone This is a simple high-speed replacement for the PRINT statement which works in CGA graphics mode (SCREEN 2). It does not interpret control codes, support graphics characters (ASCII 128-255), or update the cursor position, in return for which it is much faster than PRINT. The Fast% parameter is ignored at the moment-- top speed is always used, which may cause flickering on some CGAs. GQPrint St$, Row%, Column%, Fast% St$ string to display Row% row (1-25) Column% column (1-80) Fast% not used Name : GrafPrint (Graphics Print) Class : Display Level : Clone This is a flexible replacement for the PRINT statement which operates in graphics mode. It allows you to display text at graphics coordinates instead of text coordinates for better alignment with graphs and so forth. It also lets you specify the size of the font-- you can stretch it in either vertical or horizontal directions, or both, using a font multiplier value. The disadvantages of this routine are that it is slower than an ordinary PRINT, only does foreground printing (if you need a background color, you need to fill that in yourself beforehand), won't do automatic wrap or scroll, and won't handle control codes or graphics characters (ASCII 0-31, 127-255). The font is based on the normal CGA graphics font, which uses an 8x8 grid for each character. GrafPrint will work in any graphics mode. GrafPrint St$, X%, Y%, High%, Wide%, Colour% St$ string to display X% graphics column to start at Y% graphics row to start at High% font height multiplier Wide% font width multiplier Colour% foreground color for string Name : GrafRest (Graphics Restore) Class : Display Level : Clone This routine allows you to restore a SCREEN 1 (CGA, 320x200, 4 color) or SCREEN 2 (CGA, 640x200, 2 color) display that was saved using GrafSave (see). GrafRest DSeg%, DOfs% DSeg% segment of storage array, returned by VARSEG DOfs% offset of storage array, returned by VARPTR Name : GrafSave (Graphics Save) Class : Display Level : Clone This routine allows you to save a SCREEN 1 (CGA, 320x200, 4 color) or SCREEN 2 (CGA, 640x200, 2 color) display that can be restored using GrafRest (see). The array used to hold the screen must contain 16,000 bytes. For an integer array, this means that you must create the array by DIM Array%(1 TO 8000). GrafSave DSeg%, DOfs% DSeg% segment of storage array, returned by VARSEG DOfs% offset of storage array, returned by VARPTR Name : GXQPrint (Graphics Extended Quick Print) Class : Display Level : Clone This is a simple high-speed replacement for the PRINT statement which works in CGA graphics mode (SCREEN 1). It does not interpret control codes, support graphics characters (ASCII 128-255), or update the cursor position, in return for which it is much faster than PRINT. This routine can also be used in SCREEN 2, where it will display the string in shades instead of in color (using 40 columns/row). The Fast% parameter is ignored at the moment-- top speed is always used, which may cause flickering on some CGAs. GXQPrint St$, Row%, Column%, Fore%, Fast% St$ string to display Row% row (1-25) Column% column (1-40) Fore% foreground color (0-3) Fast% not used Name : GXQPrint1 (Graphics Extended Quick Print) Class : Display Level : Clone This is a high-speed replacement for the PRINT statement which works in CGA graphics mode (SCREEN 1). It does not interpret control codes or update the cursor position, in return for which it is much faster than PRINT. This routine can also be used in SCREEN 2, where it will display the string in shades instead of in color (using 40 columns/row). The Fast% parameter is ignored at the moment-- top speed is always used, which may cause flickering on some CGAs. GXQPrint1 St$, Row%, Column%, Fore%, Back%, Fast% St$ string to display Row% row (1-25) Column% column (1-40) Fore% foreground color (0-3) Back% background color (0-3) Fast% not used Name : HandleInfo (Handle Information) Class : Miscellaneous Level : DOS HandleInfo tells you whether a file handle refers to a file or to a device. If the handle does not exist, an error code will be returned. This is for file handles as returned by FOpen1 and FCreate. It can also be used with file numbers associated with OPEN, via a BASIC function that was introduced with QuickBASIC 4.0: Handle% = FILEATTR(FileNumber%, 2) See FClose1 for a list of predefined handles. HandleInfo Handle%, Device%, ErrCode% Handle% file handle ------- Device% whether the handle refers to a device (0 no) ErrCode% whether there was an error (0 no) Name : HCls (Hercules CLS) Class : Display Level : Clone This routine clears a Hercules graphics screen to the specified color. Routines in this series are: HCls, HLine, HMode, HPrint, HSetPixel, HTestPixel HCls Colour% Colour% color (0-1) Name : HiByte% (High Byte) Class : Numeric Level : Any This function returns the high byte of an integer. Byte% = HiByte%(Nr%) Nr% integer ------- Byte% value of the most significant byte Name : HiLite (Highlight) Class : Display Level : Clone This routine allows you to highlight text on the screen. It works in text modes only and always displays to the visible screen page. See also ReColorArea, which lets you highlight any rectangular area of the screen. HiLite Row%, LCol%, RCol%, VAttr% Row% row on which to highlight LCol% left column (where highlight starts) RCol% right column (where highlight ends) VAttr% new color (see CalcAttr) Name : HiWord% (High Word) Class : Numeric Level : Any This function returns the high word of a long integer. Word% = HiWord%(Nr&) Nr& long integer ------- Word% value of the most significant word Name : HLine (Hercules LINE) Class : Display Level : Clone This routine draws a line on a Hercules graphics screen. Routines in this series are: HCls, HLine, HMode, HPrint, HSetPixel, HTestPixel HLine X1%, Y1%, X2%, Y2%, Colour% X1% starting graphics column (0-719) Y1% starting graphics row (0-347) X2% ending graphics column (0-719) Y2% ending graphics row (0-347) Colour% color (0-1) Name : HMode (Hercules Mode) Class : Display Level : Clone This routine switches between text mode and Hercules graphics mode. Use HInit first to initialize the graphics mode appropriately. HMode will clear page 0 when graphics mode is entered. Page 1, if it exists, is not cleared. PBClone does not support page 1 in any respect. Routines in this series are: HCls, HLine, HMode, HPrint, HSetPixel, HTestPixel HMode Graphics% Graphics% display mode to set (0 text, else graphics) Name : HPrint (Hercules Print) Class : Display Level : Clone This routine displays text in Hercules graphics mode. It uses the full resolution of the screen, so text is 90 columns by 43 rows. This gives you more space than even the largest EGA text mode, which is only 80x43. Routines in this series are: HCls, HLine, HMode, HPrint, HSetPixel, HTestPixel HPrint St$, Row%, Column% St$ text to display Row% row (1-43) Column% column (1-90) Name : HSetPixel (Hercules Set Pixel) Class : Display Level : Clone This routine draws a dot on a Hercules graphics screen. Routines in this series are: HCls, HLine, HMode, HPrint, HSetPixel, HTestPixel HSetPixel X%, Y%, Colour% X% graphics column (0-719) Y% graphics row (0-347) Colour% color (0-1) Name : HTestPixel (Hercules Test Pixel) Class : Display Level : Clone This routine returns the color of a dot on a Hercules graphics screen. Routines in this series are: HCls, HLine, HMode, HPrint, HSetPixel, HTestPixel Colour% = HTestPixel%(X%, Y%) X% graphics column (0-719) Y% graphics row (0-347) ------- Colour% color (0-1) Name : IdentifyFile (Identify File) Class : Disk Level : DOS Given a file name, this routine attempts to identify what kind of file it is. Most information is derived from the file extension, but some files are processed more deeply. For instance, a file named "UNKNOWN.BAS" will be checked to see if it is source code (tokenized GWBASIC format, tokenized QuickBASIC format, or plain ASCII text) or a binary BSAVE/BLOAD image (which is further categorized as to whether it is a screen image, and if so, for what kind of display). Descript$ = SPACE$(80) IdentifyFile FileName$, Descript$, DescrLen% Descript$ = LEFT$(Descript$, DescrLen%) FileName$ name of the file to identify ------- Descript$ description of the file (init to at least 80 chars) DescrLen% length of the description Name : InitPtr (Initialize Pointers) Class : Array management Level : Any This routine initializes an array of pointers for use with the pointer sort routines (PSortD, et al). It may also be useful for other purposes. Each element of the array is set equal to its index (the first element is set to 1, the second to 2, and so forth). Arrays are expected to begin at element 1. You may specify the last element to initialize, allowing you to use only part of an array. InitPtr Ptr%(), Elements% Ptr%() array to initialize Elements% number of elements to initialize ------- Ptr%() initialized array Name : InsChr (Insert Character) Class : Display Level : Clone The InsChr routine inserts a space at the specified screen location. InsChr Row%, Column% Row% row of character Column% column of character Name : InsLine (Insert Line) Class : Display Level : BIOS This routine inserts a blank line at the specified row of the screen. InsLine Row%, VAttr% Row% row to insert VAttr% color/attribute to use on new row (see CalcAttr) Name : Int2Date (Integer to Date) Class : Time Level : Any This routine undoes the results of the Date2Int routine. It expands a single integer into month, day, and year values. The storage format is identical to that used by DOS for file dates, by the way, so this routine makes an apt companion for LoadDirFull. See also Int2DateSt$, a version of this routine which returns a string instead of numbers. Int2Date MonthNr%, DayNr%, YearNr%, IntDate% IntDate% date compressed into an integer ------- MonthNr% month number (1-12) DayNr% day (1-31) YearNr% year (1980-2079; see above for two-digit years) Name : Int2DateSt$ (Integer to Date String) Class : Time Level : Any This routine undoes the results of the Date2Int routine. It expands a single integer into a date string with the format MM-DD-YYYY. The storage format is identical to that used by DOS for file dates, by the way, so this routine makes an apt companion for LoadDirFull. See also Int2Date, a version of this routine which returns month, day, and year numbers instead of a string. DateSt$ = Int2DateSt$(IntDate%) IntDate% date compressed into an integer ------- DateSt$ uncompressed date in MM-DD-YYYY format. Name : Int2Time (Integer to Time) Class : Time Level : Any This routine undoes the results of the Time2Int routine. It expands a single integer into hour, minute, and second values. Note that the seconds will always be even, due to the storage format. The storage format is identical to that used by DOS for file times, by the way, so this routine makes an apt companion for LoadDirFull. See also Int2TimeSt$, a version of this routine which returns a string instead of numbers. Int2Time HourNr%, MinuteNr%, SecondNr%, IntTime% IntTime% time compressed into an integer ------- HourNr% hour (0-23) MinuteNr% minute SecondNr% second Name : Int2TimeSt$ (Integer to Time String) Class : Time Level : Any This routine undoes the results of the Time2Int routine. It expands a single integer into hour, minute, and second values. Note that the seconds will always be even, due to the storage format. The storage format is identical to that used by DOS for file times, by the way, so this routine makes an apt companion for LoadDirFull. See also Int2Time, a version of this routine which returns hour, minute, and second numbers instead of a string. TimeSt$ = Int2TimeSt$(IntTime%) IntTime% time compressed into an integer ------- TimeSt$ uncompressed time in HH:MM:SS format Name : IntVector (Interrupt Vector) Class : Miscellaneous Level : DOS The IntVector routine retrieves the address of a specified interrupt handler. If there is no interrupt handler, the results will normally be zero, although early DOS versions did not always have the sense to initialize unused vectors that way. IntVector DSeg%, DOfs%, Interrupt% Interrupt% interrupt number to examine ------- DSeg% segment of the interrupt handler DOfs% offset of the interrupt handler Name : IRead (Integer Read) Class : Disk Level : DOS This routine reads an integer (two binary bytes) from a file. For some applications, you might prefer LIRead, which reads an integer from a file into a zero-extended long integer-- which essentially provides support for unsigned integers (0-65535). The file must have been opened using FCreate or FOpen1. IRead Handle%, Value%, ErrCode% Handle% file handle ------- Value% integer read from file ErrCode% DOS error code (0 if no error) Name : IsAlNum% (Is Alphanumeric?) Class : String Level : Any This function returns whether a character is alphabetic or numeric. Functions in this family include: IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower, IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit IsIt% = IsAlNum%(Ch$) Ch$ character to check ------- IsIt% -1 if the character is alphabetic or numeric Name : IsAlpha% (Is Alphabetic?) Class : String Level : Any This function returns whether a character is alphabetic. Functions in this family include: IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower, IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit IsIt% = IsAlpha%(Ch$) Ch$ character to check ------- IsIt% -1 if the character is alphabetic Name : IsASCII% (Is ASCII?) Class : String Level : Any This function returns whether a character is ASCII. This is true if the character ranges from CHR$(0)-CHR$(127). Functions in this family include: IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower, IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit IsIt% = IsASCII%(Ch$) Ch$ character to check ------- IsIt% -1 if the character is ASCII Name : IsCntrl% (Is Control?) Class : String Level : Any This function returns whether a character is a control code. This is true for CHR$(0)-CHR$(32) and CHR$(127). Functions in this family include: IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower, IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit IsIt% = IsCntrl%(Ch$) Ch$ character to check ------- IsIt% -1 if the character is a control code Name : IsDigit% (Is Digit?) Class : String Level : Any This function returns whether a character is numeric. Functions in this family include: IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower, IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit IsIt% = IsDigit%(Ch$) Ch$ character to check ------- IsIt% -1 if the character is a digit Name : IsLower% (Is Lowercase?) Class : String Level : Any This function returns whether a character is a lowercase letter. Functions in this family include: IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower, IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit IsIt% = IsLower%(Ch$) Ch$ character to check ------- IsIt% -1 if the character is a lowercase letter Name : IsPrint% (Is Printable?) Class : String Level : Any This function returns whether a character is printable. This is true for CHR$(32)-CHR$(126). Functions in this family include: IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower, IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit IsIt% = IsPrint%(Ch$) Ch$ character to check ------- IsIt% -1 if the character is printable Name : IsPunct% (Is Punctuation?) Class : String Level : Any This function returns whether a character is punctuation. This is true for any ASCII character that is not alphabetic, numeric, or a control code. Functions in this family include: IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower, IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit IsIt% = IsPunct%(Ch$) Ch$ character to check ------- IsIt% -1 if the character is punctuation Name : IsSpace% (Is Space?) Class : String Level : Any This function returns whether a character is white space. This includes Space, Carriage Return, Horizontal Tab, Vertical Tab, LineFeed, and FormFeed characters. Functions in this family include: IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower, IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit IsIt% = IsSpace%(Ch$) Ch$ character to check ------- IsIt% -1 if the character is white space Name : IStr$ (Integer STR$) Class : String Level : Any This function is identical to the BASIC function STR$, but is somewhat smaller. It is only for integer values. If you prefer not to have a leading blank for non-negative numbers, use the IStrNB$ function instead. St$ = IStr$(Number%) Number% integer to convert ------- St$ string form of the number Name : IStrNB$ (Integer STR$, No Blank) Class : String Level : Any This function is similar to the BASIC function STR$, but is somewhat smaller. It is only for integer values. Unlike the STR$ function, this function does not add a leading blank to non-negative numbers. If you prefer to have a leading blank for non-negative numbers, use the IStr$ function instead. St$ = IStrNB$(Number%) Number% integer to convert ------- St$ string form of the number Name : IsUpper% (Is Uppercase?) Class : String Level : Any This function returns whether a character is an uppercase letter. Functions in this family include: IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower, IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit IsIt% = IsUpper%(Ch$) Ch$ character to check ------- IsIt% -1 if the character is uppercase Name : IsXDigit% (Is Hex Digit?) Class : String Level : Any Functions in this family include: IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower, IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit This function returns whether a character is a hexadecimal digit. IsIt% = IsXDigit%(Ch$) Ch$ character to check ------- IsIt% -1 if the character is a hex digit Name : IVal% (Integer VAL) Class : Numeric Level : Any This routine is similar to the BASIC function VAL, but is much faster. If you are not using floating point numbers, this routine may also decrease the size of your program significantly, since it won't cause BASIC to pull in its floating point routines as VAL does. Unlike VAL, this routine only converts strings to integer values. It will not handle hex or octal strings. It will not notify you if there is an overflow error. Finally, although IVal% will ignore leading blanks, it assumes that a number may not contain blanks, whereas VAL will ignore blanks in the middle of a number: VAL(" 12 34") returns 1234 IVal%(" 12 34") returns 12 Note that, like VAL (but unlike the IVal% function in ProBas), multiple negation is considered illegal. For example, IVal%("--1") returns zero. Number% = IVal%(St$) St$ string to convert ------- Number% integer form of string (0 if there isn't one) Name : IWrite (Integer Write) Class : Disk Level : DOS This routine writes an integer (two binary bytes) to a file. The file must have been opened using FCreate or FOpen1. IWrite Handle%, Value%, ErrCode% Handle% file handle Value% integer to write to file ------- ErrCode% DOS error code (0 if no error) Name : KbdType (Keyboard Type) Class : Input / Equipment Level : Clone This routine tells you if an enhanced (101-key) keyboard is available. If KbdType is not entirely sure that an enhanced keyboard is available, it plays safe and assumes there isn't one. This avoids possible disaster on older PCs. KbdType Enhanced% ------- Enhanced% whether keyboard is of the enhanced type (0 no) Name : KbdType2% (Keyboard Type) Class : Input / Equipment Level : Clone This routine tells you if an enhanced (101-key) keyboard is available. If KbdType2% is not entirely sure that an enhanced keyboard is available, it plays safe and assumes there isn't one. This avoids possible disaster on older PCs. Enhanced% = KbdType2% ------- Enhanced% whether keyboard is of the enhanced type (0 no) Name : KeyPress (detect Key Press) Class : Input Level : DOS This routine works like the Turbo/Power BASIC function INSTAT. It tells you whether there is a key waiting to be processed. KeyPress KeyHit% ------- KeyHit% whether a key is waiting (0 if no) Name : KVal& (Kilobyte VAL) Class : Numeric Level : Any This routine is similar to the BASIC function VAL, but is much faster. The number returned is divided by 1024, which is useful if you're dealing in terms of kilobytes. If you are not using floating point numbers, this routine may decrease the size of your program significantly, since it won't cause BASIC to pull in its floating point routines as VAL does. Unlike VAL, this routine only converts strings to long integer values. It will not handle hex or octal strings. It will not notify you if there is an overflow error. Finally, although KVal& will ignore leading blanks, it assumes that a number may not contain blanks, whereas VAL will ignore blanks in the middle of a number. Note that, like VAL (but unlike the KVal& function in ProBas), multiple negation is considered illegal. For example, KVal&("--10000") returns zero. Number& = KVal&(St$) St$ string to convert ------- Number& long integer form of string, divided by 1024 Name : LClose (L/I/M Close) Class : Memory Level : BIOS This routine closes a block of expanded memory that was opened for access by LOpen. It is important to close the block when you are finished with it, to return it to the free memory pool. Routines in this suite include: LOpen, LGet, LPut, LClose. LClose EMSHandle% EMSHandle% handle of the expanded memory block Name : LGet (L/I/M Get) Class : Memory Level : BIOS This routine gets a block of data from expanded memory that was opened for access by LOpen. The amount of data is specified in words; one word is the same as two bytes. An integer takes up a word, long integers and single precision numbers require two words, and double precision numbers take four. Routines in this suite include: LOpen, LGet, LPut, LClose. LGet EMSHandle%, DSeg%, DOfs%, Words% EMSHandle% handle of the expanded memory block DSeg% segment of place to store data DOfs% offset of place to store data Words% words to get from expanded memory Name : LIRead (Long Integer Read) Class : Disk Level : DOS This routine reads an integer from a file into a long integer. The integer is zero-extended into the long, providing effective support for unsigned integers (a range of 0-65535). The file must have been opened using FCreate or FOpen1. LIRead Handle%, Value&, ErrCode% Handle% file handle ------- Value& integer read from file ErrCode% DOS error code (0 if no error) Name : LIWrite (Long Integer Write) Class : Disk Level : DOS This routine writes an integer to a file from a long integer. This makes it easier to support unsigned integers (with a range of 0-65535). The file must have been opened using FCreate or FOpen1. LIWrite Handle%, Value&, ErrCode% Handle% file handle Value& integer to write to file ------- ErrCode% DOS error code (0 if no error) Name : LoadDir (Load Directory) Class : Disk Level : DOS Given a filespec with wildcards and a file attribute, this routine loads a list of all matching files into an array. The array must be of fixed-length string type, with 12 characters for each filename. You can find out how large to DIM the array by using the FileCount routine. The attribute can be any of the usual file attributes: 1 Read-Only 2 Hidden 4 System 16 Directory You can combine attributes by adding their values. For instance, to search for hidden directories, you'd use an attribute of 18. By default, DOS returns normal files as well as files which have the specified attributes, so an attribute of 18 would get you normal files, hidden files, directories, and hidden directories. However, LoadDir can be made to screen out unwanted files-- just negate the attribute to force only files of that attribute to be counted. For example, an attribute of -18 would return only hidden subdirectories. NOTE: we use FilAttr%, not FileAttr%, because BASIC has an internal function named FILEATTR. LoadDir FileSpec$, FilAttr%, DSeg%, DOfs%, ErrCode% FileSpec$ search file specification (may contain wildcards) FilAttr% search file attribute DSeg% segment of array (use VARSEG) DOfs% offset of array (use VARPTR) ------- ErrCode% error code (0 if no error) Name : LoadDirAll (Load Directory, All info) Class : Disk Level : DOS Given a filespec with wildcards and a file attribute, this routine loads a list of all matching files into an array. All available information about the file is included: name, size, time, date, and attribute. The array must be of the TYPE shown below. You can find out how large to DIM the array by using the FileCount routine. TYPE DirType FilAttr AS STRING * 1 FilTime AS INTEGER FilDate AS INTEGER FilSize AS LONG FilName AS STRING * 12 END TYPE You can change the names if you like, but don't alter the order of the information. You can decode the file attribute with the ASC function, then process it with ExplainFAttr$. The file time and date can be decoded with the Int2Time and Int2Date or Int2TimeSt$ and Int2DateSt$ routines. The attribute can be any of the usual file attributes: 1 Read-Only 2 Hidden 4 System 16 Directory You can combine attributes by adding their values. For instance, to search for hidden directories, you'd use an attribute of 18. By default, DOS returns normal files as well as files which have the specified attributes, so an attribute of 18 would get you normal files, hidden files, directories, and hidden directories. However, LoadDir can be made to screen out unwanted files-- just negate the attribute to force only files of that attribute to be counted. For example, an attribute of -18 would return only hidden subdirectories. NOTE: we use FilAttr%, not FileAttr%, because BASIC has an internal function named FILEATTR. LoadDir FileSpec$, FilAttr%, DSeg%, DOfs%, ErrCode% FileSpec$ search file specification (may contain wildcards) FilAttr% search file attribute DSeg% segment of array (use VARSEG) DOfs% offset of array (use VARPTR) ------- ErrCode% error code (0 if no error) Name : LoByte% (Low Byte) Class : Numeric Level : Any This function returns the low byte of an integer. Byte% = LoByte%(Nr%) Nr% integer ------- Byte% value of the least significant byte Name : Locase (Lowercase) Class : String Level : Any This routine, like BASIC's LCASE$ function, converts a string to lowercase. Since it doesn't have to create a new return string (a fairly slow process), it's faster than the BASIC equivalent. See also Locase1. Locase St$ St$ string to be put into lowercase ------- St$ lowercase string Name : Locase1 (Lowercase) Class : String Level : Any This routine, like BASIC's LCASE$ function, converts a string to lowercase. It converts letters in the extended character set as well as the usual letters, making it well suited for text which may not be in English. Note that DOS 5.0 and later versions provide National Language Support which includes conversion to uppercase (not lowercase, unfortunately). So, if you merely need the characters in a known state, rather than lowercase, you would do better to use the Upcase1 routine. Locase1 assumes the U.S. character set, which may well not be appropriate. See also Locase. Locase1 St$ St$ string to be put into lowercase ------- St$ lowercase string Name : LogicalDrives% (Logical Drives) Class : Disk / Equipment Level : DOS This function returns the number of logical drives available. A logical drive corresponds roughly to a drive letter-- it may point to zero or more actual devices. For instance, on a one-floppy system, both A: and B: point to the same drive. On a partitioned hard drive, both C: and D: may point to different areas of the same drive. Drive E: may point to a RAMdisk, or maybe it doesn't point to anything at all. As you can see, knowing the number of logical drives doesn't tell you much about what's actually there. However, it does give you an upper limit on the number of drive letters available, which is a good place to start. Drives% = LogicalDrives% ------- Drives% number of logical drives Name : LOpen (L/I/M Open) Class : Memory Level : BIOS This routine opens a block of expanded memory for access. The size of the block is specified in words; one word is the same as two bytes. An integer takes up a word, long integers and single precision numbers require two words, and double precision numbers take four. This allows you to store up to 64K in each EMS block that you open. Note that LOpen expects an EMS driver to be available. If you are not certain on this point, use GetLIMM beforehand to make sure. Routines in this suite include: LOpen, LGet, LPut, LClose. LOpen Words%, EMSHandle%, ErrCode% Words% size of expanded memory block to allocate ------- EMSHandle% handle of the expanded memory block ErrCode% error code (0 if no error) Name : LoWord% (Low Word) Class : Numeric Level : Any This function returns the low word of a long integer. Word% = LoWord%(Nr&) Nr& long integer ------- Word% value of the least significant word Name : LPut (L/I/M Put) Class : Memory Level : BIOS This routine puts a block of data into expanded memory that was opened for access by LOpen. The amount of data is specified in words; one word is the same as two bytes. An integer takes up a word, long integers and single precision numbers require two words, and double precision numbers take four. Routines in this suite include: LOpen, LGet, LPut, LClose. LPut EMSHandle%, DSeg%, DOfs%, Words% EMSHandle% handle of the expanded memory block DSeg% segment of place from which to get data DOfs% offset of place from which to get data Words% words to put into expanded memory Name : LRead (Long Read) Class : Disk Level : DOS This routine reads a long integer (four binary bytes) from a file. The file must have been opened using FCreate or FOpen1. LRead Handle%, Value&, ErrCode% Handle% file handle ------- Value& long integer read from file ErrCode% DOS error code (0 if no error) Name : LRotate (Left Rotate string) Class : String Level : Any Many years ago, I wrote one of the first terminal programs for the PC. It died a horrible death when Qmodem came out... sigh. This routine comes from that experience. It rotates the characters in a string left once (e.g., "ABCDE" becomes "BCDEA"). I used this in my routine to dial a list of BBSes, skipping to the next one if the current one was busy. LRotate can also be handy for things like scrolling a long message across the screen (you just PRINT LEFT$(Message$, 80); then delay a bit, LRotate and do it again). See also RRotate. LRotate St$ St$ string to be rotated left once ------- St$ string after being rotated left once Name : LScroll (Left Scroll) Class : Display Level : Clone This routine scrolls any selected part of the display left. You may scroll as many times as you like, or scroll "zero" times to totally clear the selected part of the display. LScroll TopRow%, LeftCol%, BottomRow%, RightCol%, Times% TopRow% top row of the area to scroll LeftCol% left column of the area to scroll BottomRow% top row of the area to scroll RightCol% left column of the area to scroll Times% number of times (or rows) to scroll Name : LVal& (Long integer VAL) Class : Numeric Level : Any This routine is similar to the BASIC function VAL, but is much faster. If you are not using floating point numbers, this routine may also decrease the size of your program significantly, since it won't cause BASIC to pull in its floating point routines as VAL does. Unlike VAL, this routine only converts strings to long integer values. It will not handle hex or octal strings. It will not notify you if there is an overflow error. Finally, although LVal& will ignore leading blanks, it assumes that a number may not contain blanks, whereas VAL will ignore blanks in the middle of a number: VAL(" 12 34") returns 1234 LVal&(" 12 34") returns 12 Note that, like VAL (but unlike the LVal& function in ProBas), multiple negation is considered illegal. For example, LVal&("--1") returns zero. Number& = LVal&(St$) St$ string to convert ------- Number& long integer form of string (0 if there isn't one) Name : LWrite (Long Write) Class : Disk Level : DOS This routine writes a long integer to a file. The file must have been opened using FCreate or FOpen1. LWrite Handle%, Value&, ErrCode% Handle% file handle Value& long integer to write to file ------- ErrCode% DOS error code (0 if no error) Name : MakeSub (Make Subdirectory) Class : Disk Level : DOS Like the DOS MD (or MKDIR) command, this routine creates a new subdirectory. MakeSub SubDir$, ErrCode% SubDir$ name of new subdirectory ------- ErrCode% error code: 0 if none, else DOS Error Name : MatchFile (Match File) Class : Disk / String Level : Any The MatchFile routine tells you whether a given filename matches a file specification which may contain wildcards. The filename itself should not contain wildcards. Neither the filename nor filespec should include drive or subdirectory specifications. One way of using this is in processing file exclusion lists. The FindFirstF routine allows you to find files that match a given filespec; to this, you could add a MatchFile-based routine which would screen out files that match a different filespec. Such a routine would allow you to create utilities to do things like "DIR *.* /EXCEPT=*.BAS". MatchFile FileSpec$, FileName$, IsMatch% FileSpec$ master file pattern (may contain wildcards) FileName$ name of file to test against the master pattern ------- IsMatch% 0 if the filename doesn't match the filespec Name : Max% (Maximum) Class : Numeric Level : Any This function returns the larger of two integers. It can be handy in sorting routines or for keeping a value within a desired range. Larger% = Max%(First%, Second%) First% one integer Second% another integer ------- Larger% larger of the two integers Name : MaxD# (Maximum Double precision) Class : Numeric Level : Any This function returns the larger of two double-precision numbers. It can be handy in sorting routines or for keeping a value within a desired range. Larger# = MaxD#(First#, Second#) First# one number Second# another number ------- Larger# larger of the two numbers Name : MaxL& (Maximum Long integer) Class : Numeric Level : Any This function returns the larger of two long integers. It can be handy in sorting routines or for keeping a value within a desired range. Larger& = MaxL&(First&, Second&) First& one long integer Second& another long integer ------- Larger& larger of the two long integers Name : MaxS! (Maximum Single precision) Class : Numeric Level : Any This function returns the larger of two single-precision numbers. It can be handy in sorting routines or for keeping a value within a desired range. Larger! = MaxS!(First!, Second!) First! one number Second! another number ------- Larger! larger of the two numbers Name : MeanAverageD (Mean Average Double precision) Class : Array management Level : Any This routine averages the specified range of elements in an array of double precision numbers. The form of averaging used is called the "mean", which is the sum of all of the elements divided by the number of elements involved. This is the most common method of averaging a list of numbers. MeanAverageD Array#(), First%, Last%, Average#, ErrCode% Array#() array to be averaged First% array element to start with Last% array element to end with ------- Average# average value of the specified elements ErrCode% 0 if there was no error Name : MeanAverageI (Mean Average Integer) Class : Array management Level : Any This routine averages the specified range of elements in an array of integer numbers. The form of averaging used is called the "mean", which is the sum of all of the elements divided by the number of elements involved. This is the most common method of averaging a list of numbers. MeanAverageI Array%(), First%, Last%, Average%, ErrCode% Array() array to be averaged First% array element to start with Last% array element to end with ------- Average% average value of the specified elements ErrCode% 0 if there was no error Name : MeanAverageL (Mean Average Long integer) Class : Array management Level : Any This routine averages the specified range of elements in an array of long integer numbers. The form of averaging used is called the "mean", which is the sum of all of the elements divided by the number of elements involved. This is the most common method of averaging a list of numbers. MeanAverageL Array&(), First%, Last%, Average&, ErrCode% Array&() array to be averaged First% array element to start with Last% array element to end with ------- Average& average value of the specified elements ErrCode% 0 if there was no error Name : MeanAverageS (Mean Average Single precision) Class : Array management Level : Any This routine averages the specified range of elements in an array of single precision numbers. The form of averaging used is called the "mean", which is the sum of all of the elements divided by the number of elements involved. This is the most common method of averaging a list of numbers. MeanAverageS Array!(), First%, Last%, Average!, ErrCode% Array!() array to be averaged First% array element to start with Last% array element to end with ------- Average! average value of the specified elements ErrCode% 0 if no error Name : MemSwap (Memory Swap) Class : Memory Level : Any MemSwap swaps the contents of one area of memory with another. This can be used for a variety of things, from swapping a saved screen with the actual screen to exchanging the contents of two arrays. MemSwap DSeg1%, DOfs1%, DSeg2%, DOfs2%, Bytes% DSeg1% segment of first memory area DOfs1% offset of first memory area DSeg2% segment of second memory area DOfs2% offset of second memory area Bytes% bytes to swap Name : Min% (Minimum) Class : Numeric Level : Any This function returns the smaller of two integers. It can be handy in sorting routines or for keeping a value within a desired range. Smaller% = Min%(First%, Second%) First% one integer Second% another integer ------- Smaller% smaller of the two integers Name : MinD# (Minimum Double precision) Class : Numeric Level : Any This function returns the smaller of two double-precision numbers. It can be handy in sorting routines or for keeping a value within a desired range. Smaller# = MinD#(First#, Second#) First# one number Second# another number ------- Smaller# smaller of the two numbers Name : MinL& (Minimum Long integer) Class : Numeric Level : Any This function returns the smaller of two long integers. It can be handy in sorting routines or for keeping a value within a desired range. Smaller& = MinL&(First&, Second&) First& one long integer Second& another long integer ------- Smaller& smaller of the two long integers Name : MinS! (Minimum Single precision) Class : Numeric Level : Any This function returns the smaller of two single-precision numbers. It can be handy in sorting routines or for keeping a value within a desired range. Smaller! = MinS!(First!, Second!) First! one number Second! another number ------- Smaller! smaller of the two numbers Name : MMButton (Mouse Button) Class : Mouse Level : BIOS The MMButton routine allows you to find out which mouse buttons are pressed. Although it will work with any mouse, it is designed specifically for a mouse with two buttons (see also MMButton3). If you want to find out which buttons were pressed in the past, rather than being pressed now, try MMClick instead. This routine will not work properly if there is no mouse available. Use the MMCheck routine if you are not sure. MMButton LeftB%, RightB% ------- LeftB% whether the left button is pressed RightB% whether the right button is pressed Name : MMButton3 (Mouse Button for 3-button mouse) Class : Mouse Level : BIOS The MMButton3 routine allows you to find out which mouse buttons are pressed. Although it will work with any mouse, it is designed specifically for a mouse with three buttons (see also MMButton). If you want to find out which buttons were pressed in the past, rather than being pressed now, try MMClick3 instead. This routine will not work properly if there is no mouse available. Use the MMCheck routine if you are not sure. MMButton3 LeftB%, MiddleB%, RightB% ------- LeftB% whether the left button is pressed MiddleB% whether the middle button is pressed RightB% whether the right button is pressed Name : MMCheck (Mouse Check and initialize) Class : Mouse Level : BIOS This routine does a number of things. Primarily, it is intended to let you check to see if a mouse is available. It returns a zero if there is no mouse; if there is a mouse, the number of mouse buttons is returned. The mouse status is also initialized, so this is best used once at the beginning of your program. All of the other mouse routines assume that a mouse is available, so you should definitely use MMCheck if you're not sure. Otherwise, results will be unusual at best, and the computer may even lock up under some DOS versions. There is also a function version of this routine, MMCheck2%. MMCheck Buttons% ------- Buttons% number of mouse buttons (0 if no mouse is installed) Name : MMCheck2% (Mouse Check and initialize) Class : Mouse Level : BIOS This function does a number of things. Primarily, it is intended to let you check to see if a mouse is available. It returns a zero if there is no mouse; if there is a mouse, the number of mouse buttons is returned. The mouse status is also initialized, so this is best used once at the beginning of your program. All of the other mouse routines assume that a mouse is available, so you should definitely use MMCheck2% if you're not sure. Otherwise, results will be unusual at best, and the computer may even lock up under some DOS versions. There is also a sub version of this routine, MMCheck. Buttons% = MMCheck2% ------- Buttons% number of mouse buttons (0 if no mouse is installed) Name : MMClick (Mouse Click) Class : Mouse Level : BIOS The MMClick routine allows you to find out which mouse buttons have been pressed since you last checked, and how many times they were pressed. Although it will work with any mouse, it is designed specifically for a mouse with two buttons (see also MMClick3). If you want to find out which buttons are currently being pressed, try MMButton instead. This routine will not work properly if there is no mouse available. Use the MMCheck routine if you are not sure. MMClick LeftB%, RightB% ------- LeftB% # of times left button was pressed since last check RightB% # of times right button was pressed since last check Name : MMClick3 (Mouse Click for 3-button mouse) Class : Mouse Level : BIOS The MMClick3 routine allows you to find out which mouse buttons have been pressed since you last checked, and how many times they were pressed. Although it will work with any mouse, it is designed specifically for a mouse with three buttons (see also MMClick). If you want to find out which buttons are currently being pressed, try MMButton3 instead. This routine will not work properly if there is no mouse available. Use the MMCheck routine if you are not sure. MMClick3 LeftB%, MiddleB%, RightB% ------- LeftB% # of times left button was pressed since last check MiddleB% # of times middle button was pressed since last look RightB% # of times right button was pressed since last check Name : MMCursorOff (Mouse Cursor Off) Class : Mouse Level : BIOS This routine makes the mouse cursor invisible. The mouse cursor will still function as a location indicator, in the same way that the normal cursor still functions when you make it invisible. Note that the mouse cursor is somewhat bizarre in that an "invisibility level" is kept. Every time you use MMCursorOff, the invisibility depth is increased; subsequent attempts to make the cursor visible will not actually do so until the invisibility depth reaches zero. In other words, if you call MMCursorOff when the cursor is already invisible, the cursor will not reappear until you've told it to reappear as many times as you told it to disappear. This is fairly demented, but that's the way Microsoft made it. This routine will not work properly if no mouse is installed. See MMCheck. MMCursorOff Name : MMCursorOn (Mouse Cursor On) Class : Mouse Level : BIOS This routine makes the mouse cursor visible, or tries to do so... The mouse cursor is somewhat bizarre in that an "invisibility level" is kept. Every time you use MMCursorOff, the invisibility depth is increased; subsequent attempts to make the cursor visible will not actually do so until the invisibility depth reaches zero. In other words, if you call MMCursorOff when the cursor is already invisible, the cursor will not reappear until you've told it to reappear (with MMCursorOn) as many times as you told it to disappear. This is fairly demented, but that's the way Microsoft made it. Note that there is a flaw in BASIC such that a "mouse dropping" may be left on the screen if your program is invoked at the bottom of the DOS screen, causing a scroll while the mouse cursor is visible. To avoid this, use VIEW PRINT at the beginning of your program to remove the default "status line". For the standard 80x25 text screen, this would be done like so: VIEW PRINT 1 TO 25 This routine will not work properly if no mouse is installed. See MMCheck or MMCheck2%. MMCursorOn Name : MMGetLoc (Mouse Get Location) Class : Mouse Level : BIOS This routine allows you to get the current location of the mouse cursor. It doesn't matter if the cursor is visible or invisible. The mouse cursor location is somewhat perverse in CGA and text modes, due to the sloppy design of Microsoft's original mouse driver. In text modes and both CGA graphics modes, the cursor is returned as if the screen is 640x200. To correct this for SCREEN 1, divide the X coordinate by two. To correct this for text modes, divide each coordinate by eight. This routine will not work properly if there is no mouse available. Use the MMCheck routine if you are not sure. See also GetMouseLoc, which returns the appropriate coordinates for text mode. MMGetLoc X%, Y% ------- X% X coordinate ("column") Y% Y coordinate ("row") Name : MMSetLoc (Mouse Set Location) Class : Mouse Level : BIOS This routine allows you to set the current location of the mouse cursor. It doesn't matter if the cursor is visible or invisible. The mouse cursor location is somewhat perverse in CGA and text modes, due to the sloppy design of Microsoft's original mouse driver. In text modes and both CGA graphics modes, the cursor is returned as if the screen is 640x200. To correct this for SCREEN 1, double the X coordinate. To correct this for text modes, multiply each coordinate by eight and add four. This routine will not work properly if there is no mouse available. Use the MMCheck routine if you are not sure. See also SetMouseLoc, which does the coordinate conversions for you in text mode. MMSetLoc X%, Y% X% X coordinate ("column") Y% Y coordinate ("row") Name : MMSetRange (Mouse Set Range) Class : Mouse Level : BIOS This routine allows you to set the allowable range of mouse cursor locations. The mouse cursor will not be permitted to go outside this range. It doesn't matter if the cursor is visible or invisible. The mouse cursor location is somewhat perverse in CGA and text modes, due to the sloppy design of Microsoft's original mouse driver. In text modes and both CGA graphics modes, the cursor is returned as if the screen is 640x200. To correct this for SCREEN 1, double the X coordinate. To correct this for text modes, multiply each coordinate by eight and add four. This routine will not work properly if there is no mouse available. Use the MMCheck routine if you are not sure. MMSetRange X1%, Y1%, X2%, Y2% X1% left X coordinate (upper left "column") Y1% top Y coordinate (upper left "row") X2% right X coordinate (lower right "column") Y2% bottom Y coordinate (lower right "row") Name : Month0 (Month) Class : String / Time Level : Any Given a month number, this routine tells you the name of the month. MonthName$ = SPACE$(9) Month0 MonthName$, NameLen%, MonthNr% MonthName$ = LEFT$(MonthName$, NameLen) MonthNr% month number (1-12) ------- MonthName$ name of the month. Init to at least 9 characters. NameLen% length of the month name Name : MouseBuffer (Mouse Buffer size) Class : Mouse Level : BIOS This routine is used before MouseSave in order to find out how many bytes are needed to save the mouse state. This routine will not work properly if there is no mouse available. Use the MMCheck routine if you are not sure. MouseBuffer Bytes% St$ = SPACE$(Bytes%) MouseSave St$ ------- Bytes% number of bytes needed to save the state of the mouse Name : MouseCursor (Mouse Cursor type) Class : Mouse Level : BIOS The MouseCursor routine allows you to select one of a number of graphics mouse cursors. The following types are supported: 0 hourglass ("please wait" symbol) 1 standard arrow pointer 2 pointing hand 3 crosshair 4 target (box-in-a-box pointer) 5 grabbing hand If you'd like other shapes, please suggest a few! I'll be glad to add them. MouseCursor CursorNr% CursorNr% type of mouse graphics cursor to use (see above) Name : MousePen (Mouse light Pen emulation) Class : Mouse Level : BIOS The mouse can be made to emulate a light pen, allowing you to use BASIC's light pen routines to provide a certain minimal level of support for both light pens and mice. This emulation is on by default, but you can turn it off in case there is an actual light pen attached. This routine will not work properly if there is no mouse available. Use the MMCheck routine if you are not sure. MousePen EmulatePen% EmulatePen% whether mouse should emulate light pen (0 no) Name : MouseRest (Mouse status Restore) Class : Mouse Level : BIOS This routine is for use in conjunction with MouseSave. It allows you to restore the mouse settings to a state that was saved in the past. This routine will not work properly if there is no mouse available. Use the MMCheck routine if you are not sure. MouseRest St$ St$ mouse state to restore Name : MouseSave (Mouse status Save) Class : Mouse Level : BIOS This one is handy for use in subprograms or when SHELLing to other programs that may use the mouse. It allows you to save the current mouse settings as a string. To find out how long the string should be, use MouseBuffer. This routine will not work properly if there is no mouse available. Use the MMCheck routine if you are not sure. MouseBuffer Bytes% St$ = SPACE$(Bytes%) MouseSave St$ ------- St$ saved mouse state. Init as shown above. Name : MPrint (MS-DOS Print) Class : Display Level : BIOS The MPrint routine displays text using mostly DOS services. This allows it to handle ANSI codes if an ANSI driver is installed. In addition, the output of MPrint is confined to a region of the screen that you may select with MWindow. By default, the region is 1,1 to 25,80: a full 80x25 text screen. Using MPrint is similar to using PRINT followed by a semicolon. It does not automatically move to the next line. To do so, you must MPrint a carriage return and linefeed: CHR$(13) + CHR$(10). To clear the MWindow region, MPrint a formfeed: CHR$(12). MPrint St$ St$ string to display Name : MulMatI (Multiply Matrix by Integer) Class : Array management Level : Any This routine multiplies as many elements of an integer array as you like by a given number, starting at a specified place in the array. If there was a numeric overflow at any point in the operation, an error code will be returned. MulMatI DSeg%, DOfs%, Elements%, Value%, ErrCode% DSeg% segment of the array element to start at DOfs% offset of the array element to start at Elements% number of array elements to process Value% value to multiply each array element by ------- ErrCode% error code: 0 if no error Name : MultiAND (Multiple AND) Class : String Level : Any The MultiAND routine performs an arithmetic "AND" operation on each character in a string. Among the varied uses for MultiAND is stripping the high bit from characters, as you might want to do in telecommunications or in converting WordStar files. In that case, you would use a BitMask% of 127. MultiAND St$, BitMask% St$ string to process BitMask% bit mask (0-255) with which to AND each character ------- St$ processed string Name : MultiOR (Multiple OR) Class : String Level : Any The MultiOR routine performs an arithmetic "OR" operation on each character in a string. MultiOR St$, BitMask% St$ string to process BitMask% bit mask (0-255) with which to OR each character ------- St$ processed string Name : MultiXOR (Multiple XOR) Class : String Level : Any The MultiXOR routine performs an arithmetic "XOR" operation on each character in a string. MultiXOR St$, BitMask% St$ string to process BitMask% bit mask (0-255) with which to XOR each character ------- St$ processed string Name : MWindow (MS-DOS Window) Class : Display Level : Any The MWindow routine works in conjunction with MPrint. It defines an area of the screen in which text displayed by MPrint must stay. The default window is 1,1 to 25,80. MWindow TopRow%, LeftCol%, BottomRow%, RightCol% TopRow% top row LeftCol% left column BottomRow% bottom row RightCol% right column Name : NameCase (Name Case) Class : String Level : Any This routine provides a specialized uppercase/lowercase converter designed especially for names. It converts the first letter in each word in a string to uppercase, with the rest of the word being converted to lowercase. See also NameCase2, the FUNCTION version of this routine. NameCase St$ St$ string to process ------- St$ processed string Name : NameCase2$ (Name Case) Class : String Level : Any This routine provides a specialized uppercase/lowercase converter designed especially for names. It converts the first letter in each word in a string to uppercase, with the rest of the word being converted to lowercase. See also NameCase, the SUB version of this routine. Result$ = NameCase2$(St$) St$ string to process ------- Result$ processed string Name : Num2Phone$ (compressed phone# to string) Class : Numeric String Level : Any This function takes a phone number (as encoded by Phone2Num&) and converts it to unformatted string form. Depending on the original number, the result may be 4, 7, or 10 characters in length. An invalid code will result in a null string. NOTE that this function will handle current US-style phone numbers. It expects the first three digits of a 10-digit phone number to represent an area code, where the middle digit of the area code is always either zero or one. This convention is expected to change as of 1994 or so, whereupon this function will no longer be reliable <sigh>. Result$ = Num2Phone$(PhoneNumber&) PhoneNumber& encoded phone number ------- Result$ phone number ("" if invalid number) Name : NumFormat (Number Format) Class : Numeric Level : DOS This works just like PRINT USING, but returns the results in a string rather than sending them to the display or a file. Note that an interaction between QuickBASIC, DOS and some networks means that this routine will briefly access the default drive. Strange but true. NumFormat Format$, Number#, Result$ Format$ numeric format Number# number to format ------- Result$ formatted number Name : NumProc (Numeric Processor) Class : Equipment Level : Any NumProc returns the type of numeric coprocessor installed. I haven't tried it with a 80486, but I would guess an 80486 always appears to have an 80387 (unless it's one of those brain-damaged 80486SX chips). Results are returned as follows: 0 no math chip 1 8087 2 80287 3 80387 If anyone can tell me how to better handle a 486 here, I'd appreciate it. NumProc ProcType% ------- ProcType% type of numeric coprocessor (see above) Name : NumProc2% (Numeric Processor) Class : Equipment Level : Any NumProc2% returns the type of numeric coprocessor installed. I haven't tried it with a 80486, but I would guess an 80486 always appears to have an 80387 (unless it's one of those brain-damaged 80486SX chips). Results are returned as follows: 0 no math chip 1 8087 2 80287 3 80387 If anyone can tell me how to better handle a 486 here, I'd appreciate it. ProcType% = NumProc2% ------- ProcType% type of numeric coprocessor (see above) Name : ObjScan (Object file Scan) Class : Disk Level : DOS This routine returns information about a specified .OBJ file. It returns the module name, public names, and external names. The module name is generally the name of the original file which was compiled to produce the .OBJ file. Public names are the names of routines (and sometimes variables) that can be accessed by outside programs. External names are the names of routines (and variables) that the .OBJ file expects to be provided by outside programs. External names containing "$", starting with "_" or with lowercase characters are screened out to avoid returning a huge list of BASIC internal routines. For the same reason, routines ending with "QQ" will also be screened out, as will STRINGADDRESS, STRINGASSIGN, STRINGLENGTH, and STRINGRELEASE. Y'know, it would be nice if Microsoft followed some sort of standard for its names. The public and external names are returned in string arrays. ObjScan will fail with an error code if there is insufficient space, so be sure to allow plenty of room. If scanning subprograms, a DIM to 30 or 40 elements is probably ample. If scanning large programs, you may need to increase the dimensions substantially. The ObjScan routine can be used as the basis for a simple ".OBJ info" utility or for more complex applications, such as library management. ObjScan ObjFile$, ModName$, Routine$(), External$(), ErrCode% ObjFile$ name of .OBJ file ------- ModName$ module name Routine$() public names External$() external names ErrCode% whether there was an error (0 no) Name : Odd% (Odd integer?) Class : Numeric Level : Any This function returns whether an integer is odd. If so, it returns -1, otherwise 0. Result% = Odd%(Number%) Number% number to test ------- Result% whether the number is odd Name : OddL% (Odd Long integer?) Class : Numeric Level : Any This function returns whether a long integer is odd. If so, it returns -1, otherwise 0. Result% = Odd%(Number&) Number& number to test ------- Result% whether the number is odd Name : OrSt (OR String) Class : String Level : Any This routine ORs each byte in one string with the corresponding byte in a second string. The strings must be the same length. OrSt St1$, St2$ St1$ string to OR St2$ string to OR with ------- St1$ result Name : ParseFSpec (Parse File Specification) Class : Disk Level : Any This routine splits a file specification into a drive, subdirectory, and filename. You are expected to initialize the return strings to reasonable values beforehand (1 for drive, 64 for subdirectory, 12 for filename). If the filespec may be invalid, you may wish to leave additional space to avoid potentially disastrous overflows. An alternative would be to use ExtendFSpec beforehand to check and complete the file specification. This is likely to be a good approach anyway-- these two routines complement each other nicely. Drive$ = SPACE$(1) Subdir$ = SPACE$(64) File$ = SPACE$(12) ParseFSpec FileSpec$, Drive$, DLen%, Subdir$, SLen%, File$, FLen% Drive$ = LEFT$(Drive$, DLen%) Subdir$ = LEFT$(Subdir$, SLen%) File$ = LEFT$(File$, FLen%) FileSpec$ file specification ------- Drive$ drive letter (init to 1+) DLen% length of Drive$ SubDir$ subdirectory (init to 64+) SLen% length of Subdir$ File$ file name (init to 12+) FLen% length of File$ Name : PatchDone (Patch Done) Class : Disk Level : DOS This routine closes the file opened by FindPatch. You must use PatchDone when you are finished patching the file. Routines in this set include FindPatch, SetPatch, and PatchDone. PatchDone Name : PCDat$ (PC Date) Class : Equipment Level : Clone The PCDat$ routine tells you the date of the BIOS ROM chip. This date is not always available on some (mostly older) clones, in which case "No Date" is returned. ROMDate$ = PCDat$ ------- ROMDate$ date of the BIOS ROM (xx/xx/xx). Name : PCDate (PC Date) Class : Equipment Level : Clone The PCDate routine tells you the date of the BIOS ROM chip. This date is not always available on some (mostly older) clones, in which case "No Date " is returned. See also PCDat, a function version of this routine. ROMDate$ = SPACE$(8) PCDate ROMDate$ ------- ROMDate$ date of the BIOS ROM (xx/xx/xx). Init to 8+ chars. Name : PCType (PC Type) Class : Equipment Level : Clone This routine returns the machine I.D. code. This code may not be one of the listed values for some (mostly older) clones, but the following is usually correct: I.D. ....Machine.... 255 PC or XT 254 XT 253 PCjr 252 PC AT 251 XT 250 PS/2 Model 30 249 PC Convertible 248 PS/2 Model 70 or 80 154 Compaq Portable 45 Compaq Portable Note that, for identification purposes, a PC and XT are essentially the same. The XT is simply a PC with an auto-boot hard drive. New I.D. numbers come out more or less at random from IBM, although they aren't as capricious about it as they used to be. It is useful to identify Compaq Portables as separate from PCs because those machines had an unusual display, which acts like a CGA but has the resolution (in text modes) of an MDA. Hence, the cursor size of a Compaq Portable is MDA-sized in text mode, but CGA-sized in graphics modes, even though ordinary tests will tell your program that a CGA is attached. If you intend to alter the cursor size, this is an important distinction, since the Compaq Portable was a great success and is still in wide use. Current Compaq machines, like most other clones, follow the standard IBM I.D. codes. See also PCType2, a function version of this routine. PCType MachineID% ------- MachineID% type of computer Name : PCType2% (PC Type) Class : Equipment Level : Clone This routine returns the machine I.D. code. This code may not be one of the listed values for some (mostly older) clones, but the following is usually correct: I.D. ....Machine.... 255 PC or XT 254 XT 253 PCjr 252 PC AT 251 XT 250 PS/2 Model 30 249 PC Convertible 248 PS/2 Model 70 or 80 154 Compaq Portable 45 Compaq Portable Note that, for identification purposes, a PC and XT are essentially the same. The XT is simply a PC with an auto-boot hard drive. New I.D. numbers come out more or less at random from IBM, although they aren't as capricious about it as they used to be. It is useful to identify Compaq Portables as separate from PCs because those machines had an unusual display, which acts like a CGA but has the resolution (in text modes) of an MDA. Hence, the cursor size of a Compaq Portable is MDA-sized in text mode, but CGA-sized in graphics modes, even though ordinary tests will tell your program that a CGA is attached. If you intend to alter the cursor size, this is an important distinction, since the Compaq Portable was a great success and is still in wide use. Current Compaq machines, like most other clones, follow the standard IBM I.D. codes. MachineID% = PCType2% ------- MachineID% type of computer Name : Phone2Num& (Phone# to Number) Class : Numeric String Level : Any This function converts a U.S. or Canadian phone number from string form to a long integer. It accepts phone numbers of 4, 7, 10, or 11 digits. If there are 11 digits, the first digit must be a 1. Non-numeric characters are ignored so that formatted phone numbers can be used. If the phone number is of the wrong length or otherwise does not appear to be valid, -1 is returned; otherwise, the result is a long integer which represents the phone number in a format that can be decoded by Num2Phone$. This function will accept alphabetic phone numbers and convert them to their numeric equivalents. Since it only takes 4 bytes to store a long integer, as opposed to 7 to 10 or more for the usual alphanumeric form, this can be considered a compression routine as well as a validation routine. At worst, for 4-digit phone numbers, it is exactly as efficient as a character representation. For 7 or 10-digit phone numbers, it roughly doubles your storage space. A few words on how checking is done: obviously, there is no way to tell whether a number is in use or is in fact whoever you wished to call. However, there are certain regularities to numeric phone numbers which can be used to detect blatantly false numbers. Alphabetic phone numbers do not include all the letters of the alphabet, either. This routine will check for any obvious peculiarities and warn you accordingly. NOTE that this function will handle current US-style phone numbers. It expects the first three digits of a 10-digit phone number to represent an area code, where the middle digit of the area code is always either zero or one. This convention is expected to change as of 1994 or so, whereupon this function will no longer be reliable <sigh>. Result& = Phone2Num&(PhoneNumber$) PhoneNumber$ phone number (may be formatted) ------- Result& encoded phone number (-1 if invalid number) Name : PrintBox (Print a Box) Class : Display Level : Clone This routine displays a box, filled with a character or string of your choice. Only text modes are supported. PrintBox St$, TopRow%, LftCol%, BotRow%, RhtCol%, VAttr%, _ Page%, Fast% St$ string to fill box with (one or more chars) TopRow% top row of box LftCol% left column of box BotRow% bottom row of box RhtCol% right column of box VAttr% color/attribute of box (see CalcAttr) Page% display page (for color adapters) Fast% display speed (-1 fast, 0 slow for old CGAs) Name : PrinterInit (Printer Initialize) Class : Printer Level : BIOS This routine initializes a printer in the same way as if the computer had been rebooted. Note that this will not work on serial printers, even if the MODE command was used to redirect the port. It works at the BIOS level, so it doesn't know about any fooling around DOS does. PrinterInit Port% Port% parallel port number (1-3) Name : PrinterReady% (Printer Ready) Class : Printer Level : BIOS This function lets you know if a printer is ready. It checks to make sure that the specified port exists, then makes sure a printer is connected, turned on, and has paper in it. Note that this will not work on serial printers, even if the MODE command was used to redirect the port. It works at the BIOS level, so it doesn't know about any fooling around DOS does. Ready% = PrinterReady%(Port%) Port% parallel port number (1-3) ------- Ready% whether there's a printer ready at that port Name : PrintFile (Print File) Class : Printer Level : DOS This routine sends a file to the printer. It does not paginate, spool, or anything else fancy. The LPT1 or PRN device is used by default, although you can change this using the PrtSwap routine. The predefined device handle for stdprn is used, so don't use FClose1 to free that handle if you expect to use this routine. The results could be nasty. PrintFile FileName$, ErrCode% FileName$ name of the file to print ------- ErrCode% whether there was an error (0 no, else DOS Error) Name : PrintScreen (Print Screen) Class : Display / Printer Level : BIOS Just like pressing the PrtSc/PrintScrn key on the keyboard, this routine sends the contents of the display to the printer. It is mostly designed for text modes, but use of the GRAPHICS TSR provided with DOS will allow it to print out CGA graphics displays as well. For some reason, the GRAPHICS utility does not handle Hercules, EGA or VGA displays; however, alternative utilities which provide such features may be obtained from your local BBS. PrintScreen Name : Processor (Processor) Class : Equipment Level : Any Processor returns the type of processor (CPU) installed. Results are returned as follows: 0 NEC V20 1 8088 or 8086 2 80186 3 80286 4 80386 5 80486 Note that, for most practical purposes, a NEC V20 works just like an 80186. Processor ProcType% ------- ProcType% type of CPU (see above) Name : Processor2% (Processor) Class : Equipment Level : Any Processor returns the type of processor (CPU) installed. Results are returned as follows: 0 NEC V20 1 8088 or 8086 2 80186 3 80286 4 80386 5 80486 Note that, for most practical purposes, a NEC V20 works just like an 80186. ProcType% = Processor2% ------- ProcType% type of CPU (see above) Name : PrtSc (Print Screen key) Class : Input / Printer Level : BIOS This routine allows you to disable the "print screen" key. This only affects the keyboard, not the PrintScreen routine in PBClone. When the print screen key is disabled, you can detect whether it was pressed using the GetPrtSc% function. This provides a way of using the key for your own purposes. If you disable the print screen key, be sure to enable it again before your program ends. Otherwise, the print screen key will be left in an undefined state, probably causing the computer to crash when it is next pressed. PrtSc Enable% Enable% whether print screen key should be enabled (0 if no) Name : PrtSwap (Printer Swap) Class : Printer Level : Clone It's handy to use LPRINT, but it isn't always practical. LPRINT only works on the first printer available (PRN or LPT1). With this routine, it doesn't matter. PrtSwap allows you to swap any two printer ports. Note that it's a good idea to swap the ports back to their original locations before exiting your program. You could cause major confusion otherwise! PrtSwap Port1%, Port2% Port1% number of the first port (1-3) Port2% number of the second port (1-3) Name : PSortD (Pointer Sort Double precision) Class : Array management Level : Any This routine sorts the elements in a double precision array... well, actually, it doesn't change the position of anything in the double precision array. It sorts the array using a set of pointers to the array. You can then use the pointers to refer to the array or to re-order the array yourself. Why bother with pointers? Well, it's a lot faster than sorting the numbers directly, since less information has to be swapped. It has another major advantage, though-- it allows you to sort an array without losing track of how it corresponds to any related arrays. The array is assumed to start at element 1. You may specify the last element in the array, allowing you to sort only part of an array if you like. The pointer array must be initialized so that each element is equal to its index. Either use InitPtr or do: FOR tmp% = 1 TO Elements% Ptr%(tmp%) = tmp% NEXT After this routine, you can access the sorted array via the pointer array. For instance, to print out a sorted double precision array, you'd use: FOR tmp% = 1 TO Elements% PRINT Array#(Ptr%(tmp%)) NEXT If you would like the results to be last-to-first, rather than first-to-last, just call ReverseI to reverse the pointer array (after this routine). PSortD Ptr%(), Array#(), Elements% Ptr%() pointers to array to be sorted Array#() array to be sorted Elements% number of elements in array ------- Ptr%() pointers which allow accessing array in sorted order Name : PSortI (Pointer Sort Integer) Class : Array management Level : Any This routine sorts the elements in an integer array... well, actually, it doesn't change the position of anything in the integer array. It sorts the array using a set of pointers to the array. You can then use the pointers to refer to the array or to re-order the array yourself. Why bother with pointers? It has a major advantage-- it allows you to sort an array without losing track of how it corresponds to any related arrays. The array is assumed to start at element 1. You may specify the last element in the array, allowing you to sort only part of an array if you like. The pointer array must be initialized so that each element is equal to its index. Either use InitPtr or do: FOR tmp% = 1 TO Elements% Ptr%(tmp%) = tmp% NEXT After this routine, you can access the sorted array via the pointer array. For instance, to print out a sorted integer array, you'd use: FOR tmp% = 1 TO Elements% PRINT Array%(Ptr%(tmp%)) NEXT If you would like the results to be last-to-first, rather than first-to-last, just call ReverseI to reverse the pointer array (after this routine). PSortI Ptr%(), Array%(), Elements% Ptr%() pointers to array to be sorted Array%() array to be sorted Elements% number of elements in array ------- Ptr%() pointers which allow accessing array in sorted order Name : PSortL (Pointer Sort Long integer) Class : Array management Level : Any This routine sorts the elements in a long integer array... well, actually, it doesn't change the position of anything in the long integer array. It sorts the array using a set of pointers to the array. You can then use the pointers to refer to the array or to re-order the array yourself. Why bother with pointers? Well, it's a lot faster than sorting the numbers directly, since less information has to be swapped. It has another major advantage, though-- it allows you to sort an array without losing track of how it corresponds to any related arrays. The array is assumed to start at element 1. You may specify the last element in the array, allowing you to sort only part of an array if you like. The pointer array must be initialized so that each element is equal to its index. Either use InitPtr or do: FOR tmp% = 1 TO Elements% Ptr%(tmp%) = tmp% NEXT After this routine, you can access the sorted array via the pointer array. For instance, to print out a sorted long integer array, you'd use: FOR tmp% = 1 TO Elements% PRINT Array&(Ptr%(tmp%)) NEXT If you would like the results to be last-to-first, rather than first-to-last, just call ReverseI to reverse the pointer array (after this routine). PSortL Ptr%(), Array&(), Elements% Ptr%() pointers to array to be sorted Array&() array to be sorted Elements% number of elements in array ------- Ptr%() pointers which allow accessing array in sorted order Name : PSortS (Pointer Sort Single precision) Class : Array management Level : Any This routine sorts the elements in a single precision array... well, actually, it doesn't change the position of anything in the single precision array. It sorts the array using a set of pointers to the array. You can then use the pointers to refer to the array or to re-order the array yourself. Why bother with pointers? Well, it's a lot faster than sorting the numbers directly, since less information has to be swapped. It has another major advantage, though-- it allows you to sort an array without losing track of how it corresponds to any related arrays. The array is assumed to start at element 1. You may specify the last element in the array, allowing you to sort only part of an array if you like. The pointer array must be initialized so that each element is equal to its index. Either use InitPtr or do: FOR tmp% = 1 TO Elements% Ptr%(tmp%) = tmp% NEXT After this routine, you can access the sorted array via the pointer array. For instance, to print out a sorted single precision array, you'd use: FOR tmp% = 1 TO Elements% PRINT Array!(Ptr%(tmp%)) NEXT If you would like the results to be last-to-first, rather than first-to-last, just call ReverseI to reverse the pointer array (after this routine). PSortS Ptr%(), Array!(), Elements% Ptr%() pointers to array to be sorted Array!() array to be sorted Elements% number of elements in array ------- Ptr%() pointers which allow accessing array in sorted order Name : PSortSt (Pointer Sort String) Class : Array management Level : Any This routine sorts the elements in a string array... well, actually, it doesn't change the position of anything in the string array. It sorts the array using a set of pointers to the array. You can then use the pointers to refer to the array or to re-order the array yourself. Why bother with pointers? Well, it's a lot faster than sorting the strings directly, since less information has to be swapped. It has another major advantage, though-- it allows you to sort an array without losing track of how it corresponds to any related arrays. For instance, if you have one array holding names and another holding phone numbers, this allows you to sort on names without losing track of which phone numbers are which. The array is assumed to start at element 1. You may specify the last element in the array, allowing you to sort only part of an array if you like. You can also specify whether the capitalization of letters in a string should matter for sorting purposes. The pointer array must be initialized so that each element is equal to its index. Either use InitPtr or do: FOR tmp% = 1 TO Elements% Ptr%(tmp%) = tmp% NEXT After this routine, you can access the sorted array via the pointer array. For instance, to print out a sorted string array, you'd use: FOR tmp% = 1 TO Elements% PRINT Array$(Ptr%(tmp%)) NEXT If you would like the results to be last-to-first, rather than first-to-last, just call ReverseI to reverse the pointer array (after this routine). PSortSt Ptr%(), Array$(), Elements%, CapsCount% Ptr%() pointers to array to be sorted Array$() array to be sorted CapsCount% use 0 if uppercase/lowercase distinctions don't matter Elements% number of elements in array ------- Ptr%() pointers which allow accessing array in sorted order Name : PutScreen (Put Screen) Class : Display Level : Clone This routine restores a portion of the display (which was saved to an array by DGetScreen or GetScreen) to the screen. Only text modes are supported. If your program uses multiple display pages, you can put the image onto any of those pages. A special "slow" mode is supported for the CGA, to prevent flickering (a problem only with some CGAs). If you wish to restore the entire screen, you may find ScrRest easier (see). PutScreen Array%(), TRow%, LCol%, BRow%, RCol%, Page%, Fast% Array%() array from which to restore the image TRow% top row of the desired screen area LCol% left column of the desired screen area BRow% bottom row of the desired screen area RCol% right column of the desired screen area Page% page on which to restore the display Fast% whether to use fast mode (0 no) Name : QPrint (Quick Print) Class : Display Level : Clone This is a replacement for the PRINT statement. It is less flexible in that it does not move the cursor or interpret control codes, and because it uses the color that is already on the screen instead of a specified color value. It also works only in text modes. In exchange, QPrint gives you much faster display speeds. See also XQPrint, which is a bit more flexible (and somewhat slower). QPrint St$, Row%, Column%, Page%, Fast% St$ text to display Row% starting row Column% starting column Page% page on which to display Fast% whether to use fast mode (0 no) Name : Rand% (Random number) Class : Numeric Level : Clone This is a pseudo-random number function. It returns a "random" number in a range you specify (e.g., if you pass it 10, it will return 0-9). The number is less random than you'd get from the BASIC function RND, and you can't set a random number seed a la RANDOMIZE. There is one major advantage to Rand%, however: it doesn't bring in BASIC's floating point support, which makes it much faster than RND and may make your program much smaller. Number% = Rand%(Range%) Range% range of desired pseudo-random number ------- Number% pseudo-random number from 0 to Range% - 1 Name : ReadBitF (Read Bit Field) Class : Numeric Level : Any This routine allows you to get an element of a virtual array. The actual array can be any numeric type, as it is just being used as a storage area. The virtual array is composed of numbers of a bit length that you specify (1-8). This provides efficient storage for numbers which have a limited range. See also WriteBitF. ReadBitF DSeg%, DOfs%, ElementNr&, BitLen%, Value% DSeg% segment of actual array DOfs% offset of actual array ElementNr& virtual element number (starts at 0) BitLen% bits per virtual element (1-8) ------- Value% result (0-255 or less, depending on BitLen%) Name : ReadScreen (Read Screen into string) Class : Display Level : Clone This routine reads a string off the screen. The screen must be in text mode. See also GetLine, which reads a row of text from a virtual or saved screen. Result$ = SPACE$(10) ' init to desired length ReadScreen Result$, Row%, Column%, Page% Result$ result string: init to desired length first Row% row (1-25, 1-43, etc [depends on screen mode]) Column% column (1-40, 1-80, etc [depends on mode]) Page% page (0, 0-3, etc [depends on display and mode]) Name : Reboot (Reboot) Class : Miscellaneous Level : Clone This routine restarts the computer, just like typing Control-Alt-Del at the keyboard. Reboot Name : Recolor (Recolor) Class : Display Level : Clone The Recolor routine changes all text in one color to another color. It works only in text modes. The colors are specified as attributes (see CalcAttr). Recolor OldAttr%, NewAttr% OldAttr% color to be changed NewAttr% color to which to change Name : RecolorArea (Recolor Area) Class : Display Level : Clone The RecolorArea routine changes a specified area of the screen to a specified color. It works only in text modes. The color is specified as an attribute (see CalcAttr). See also HiLite, which provides an easier way of highlighting between two columns on a single row. RecolorArea TRow%, LCol%, BRow%, RCol%, VAttr%, Page%, Fast% TRow% top row of area to recolor LCol% left column of area to recolor BRow% bottom row of area to recolor RCol% right column of area to recolor VAttr% desired color Page% display page (normally zero) Fast% whether to use fast mode (0 no) Name : RedirectIn% (Redirect Input) Class : Miscellaneous Level : DOS The RedirectIn% function allows you to determine whether input has been redirected. This lets you know whether input is coming from the keyboard or from a file or device. Input that is done by BIOS key routines (e.g., BIOSInkey) is not affected by redirection, so if you want to support redirection it is best to avoid such routines unless there is something that must come from the keyboard. Redir% = RedirectIn% ------- Redir% whether input has been redirected (0 no) Name : RedirectOut% (Redirect Output) Class : Miscellaneous Level : DOS The RedirectOut% function allows you to determine whether output has been redirected. This lets you know whether output is going to the display or to a file or device. Output that is done by direct screen writes (e.g., XQPrint) is not affected by redirection, so if you want to allow redirection it is best to avoid such routines unless there is something that must to go to the screen itself. Redir% = RedirectOut% ------- Redir% whether output has been redirected (0 no) Name : Rename (Rename file) Class : Disk Level : DOS This routine allows you to rename an ordinary file. See also RenSub. Rename CurrentName$, NewName$, ErrCode% CurrentName$ current name of the file NewName$ desired name of the file ------- ErrCode% error code: 0 if no error, else DOS Error Name : RenSub (Rename Subdirectory) Class : Disk Level : DOS This routine provides a service that was inexplicably left out of the DOS command shell. It allows you to rename a subdirectory. Note that renaming a subdirectory is only possible using old-style FCB file handling. This means that the subdirectory which you specify must be in the current directory (the routine doesn't really understand subdirectories per se, but treats them like any other file). In this implementation, no drive specification is allowed either. Finally, if there is an error, the error code may be a simple "255" instead of a useful disk error number. RenSub CurrentSub$, NewSub$, ErrCode% CurrentSub$ current name of the subdirectory NewSub$ desired name of the subdirectory ------- ErrCode% error code: 0 if no error, else DOS Error Name : Replace (Replace character) Class : String Level : Any This routine replaces all occurrences of a given character in a string with another character. Replace St$, CurCh$, NewCh$ St$ string to process CurCh$ character to be replaced NewCh$ character to replace with ------- St$ processed string Name : ReplaceString (Replace String) Class : String Level : Any This routine replaces all occurrences of a given substring within a string with another substring. The substrings may be of any length. An error code will be returned if the string to search for is null. ReplaceString St$, Old$, New$, Found%, ErrCode% St$ string to process Old$ substring to be replaced New$ substring to replace with ------- Found% whether a replacement was done (0 if no) ErrCode% whether there was an error (0 if no) Name : Retries (Retries) Class : Disk Level : DOS 3.1+ This routine allows you to adjust the handling of file-sharing errors. When such an error occurs, DOS normally retries 3 times, with a wait of 1 between tries. This allows temporary conditions, such as someone else using the file you want to access, to clear up. In many cases, though, you may want to change this delay. A shorter delay will improve response time, allowing your program to handle the error more quickly. A longer delay may be more suited for a busy network, allowing the request to proceed after a reasonable waiting period. The delay period between each retry is unfortunately machine-dependent, i.e., you will need larger delays on faster machines to achieve the same effect. This can only be considered a flaw in DOS. Note that shorter waiting periods will improve response time for your program, but may adversely affect the network. Normally, you should use the longest waiting period with which you feel comfortable. Retries Times%, WaitTime% Times% # of times to retry if file-sharing violation occurs WaitTime% amount of time to delay between retries Name : Reverse (Reverse) Class : String Level : Any This little fellow reverses the order of the characters in a string. It is one of the vital components of RInstr, but other than that I see no real use for it. On the other hand, George Boole thought that Boolean logic was of solely theoretical interest, and yet without it there would be no computers. I leave it to you to find the earth-shattering possibilities of Reverse! Reverse St$ St$ string to be reversed ------- St$ reversed string Name : ReverseD (Reverse Double precision array) Class : Array management Level : Any This routine reverses the elements in an array of double-precision numbers. This will probably be most useful for an array sorted by SortD, in case you want the numbers to go from largest to smallest. The array is assumed to start at element 1. You may specify the last element in the array, allowing you to reverse only part of an array if you like. ReverseD Array#(), Elements% Array#() array to be reversed Elements% number of elements in array ------- Array#() reversed array Name : ReverseI (Reverse Integer array) Class : Array management Level : Any This routine reverses the elements in an array of integers. This will probably be most useful for an array sorted by SortI, or a pointer array used in PSortD, PSortI, PSortL, PSortS, or PSortSt, in case you want the values to go from largest to smallest. The array is assumed to start at element 1. You may specify the last element in the array, allowing you to reverse only part of an array if you like. ReverseI Array%(), Elements% Array%() array to be reversed Elements% number of elements in array ------- Array%() reversed array Name : ReverseL (Reverse Long integer array) Class : Array management Level : Any This routine reverses the elements in an array of long integers. This will probably be most useful for an array sorted by SortL, in case you want the values to go from largest to smallest. The array is assumed to start at element 1. You may specify the last element in the array, allowing you to reverse only part of an array if you like. ReverseL Array&(), Elements% Array&() array to be reversed Elements% number of elements in array ------- Array&() reversed array Name : ReverseS (Reverse Single precision array) Class : Array management Level : Any This routine reverses the elements in an array of single-precision numbers. This will probably be most useful for an array sorted by SortS, in case you want the numbers to go from largest to smallest. The array is assumed to start at element 1. You may specify the last element in the array, allowing you to reverse only part of an array if you like. ReverseS Array!(), Elements% Array!() array to be reversed Elements% number of elements in array ------- Array!() reversed array Name : ReverseSt (Reverse String array) Class : Array management Level : Any This routine reverses the elements in a string array. This will probably be most useful for an array sorted by SortSt, in case you want the strings to be in reverse-alphabetical order. The array is assumed to start at element 1. You may specify the last element in the array, allowing you to reverse only part of an array if you like. ReverseSt Array$(), Elements% Array$() array to be reversed Elements% number of elements in array ------- Array$() reversed array Name : RInstr (Reverse INSTR) Class : String Level : Any Like INSTR, this routine tells you the position of a substring within a string. A "reverse" search is used, however-- whereas INSTR tells you the first match, RInstr tells you the last match. Similarly, whereas INSTR will tell you that a null search string matches the main string at the first position, RInstr will match on the last position. Of course, most of the time you won't be searching for a null string! RInstr MainSt$, SeekSt$, Posn% MainSt$ string to search SeekSt$ string for which to search ------- Posn% position of substring within main string (0 no match) Name : RolSt (Rotate Left String of bits) Class : String Level : Any This routine rotates the bits in a string left by a desired amount. This may be helpful for manupulating strings containing bit flags, images, et al. RolSt St$, Count% St$ string to rotate left Count% bits by which to rotate ------- St$ rotated string Name : RorSt (Rotate Right String of bits) Class : String Level : Any This routine rotates the bits in a string right by a desired amount. This may be helpful for manupulating strings containing bit flags, images, et al. RorSt St$, Count% St$ string to rotate right Count% bits by which to rotate ------- St$ rotated string Name : RotateL (Rotate Left) Class : Numeric Level : Any This routine rotates the bits in an integer left by a desired amount. RotateL Value%, Count% Value% number to rotate left Count% bits by which to rotate ------- Value% rotated number Name : RotateLL (Rotate Left Long) Class : Numeric Level : Any This routine rotates the bits in a long integer left by a desired amount. RotateLL Value&, Count% Value& number to rotate left Count% bits by which to rotate ------- Value& rotated number Name : RotateR (Rotate Right) Class : Numeric Level : Any This routine rotates the bits in an integer right by a desired amount. RotateR Value%, Count% Value% number to rotate right Count% bits by which to rotate ------- Value% rotated number Name : RotateRL (Rotate Right Long) Class : Numeric Level : Any This routine rotates the bits in a long integer right by a desired amount. RotateRL Value&, Count% Value& number to rotate right Count% bits by which to rotate ------- Value& rotated number Name : RRotate (Right Rotate string) Class : String Level : Any This routine rotates the characters in a string right once. I'll admit that I haven't found a use for this myself, but people are always coming up with new uses for things... and it complements the more useful LRotate routine. See also LRotate. RRotate St$ St$ string to be rotated right once ------- St$ string after being rotated right once Name : RScroll (Right Scroll) Class : Display Level : Clone This routine scrolls any selected part of the display right. You may scroll as many times as you like, or scroll "zero" times to totally clear the selected part of the display. RScroll TopRow%, LeftCol%, BottomRow%, RightCol%, Times% TopRow% top row of the area to scroll LeftCol% left column of the area to scroll BottomRow% top row of the area to scroll RightCol% left column of the area to scroll Times% number of times (or rows) to scroll Name : ScanKey (Scan Keyboard) Class : Input Level : BIOS This one's like INKEY$, but a little bit more subtle. It will tell you if there's a key waiting (and if so, what key it is) without actually getting the key. The key will remain available for later retrieval. Among the more common uses for this routine is to handle keys like Control-S (pause the display) and Control-C (abort). You can see if these keys have been pressed without disturbing anything else the user might have typed. DOS uses exactly this technique for handling these keys. Since BASIC doesn't go through DOS I/O, though, the only way for you to support such nice features is to write them into your program with ScanKey. ScanKey CharCode%, CharType% ------- CharType% key type: 0 none, 1 normal, 2 extended (scan code) CharCode% key ASCII or scan code Name : Scroll (Scroll) Class : Display Level : BIOS This routine scrolls any selected part of the display up. You may scroll as many times as you like, or scroll "zero" times to totally clear the selected part of the display. Note that BIOS-level scrolling can cause the screen to flicker on some CGAs due to a combination of unfortunate design factors. Scroll TopRow%, LeftCol%, BottomRow%, RightCol%, Times% TopRow top row of the area to scroll LeftCol% left column of the area to scroll BottomRow top row of the area to scroll RightCol% left column of the area to scroll Times% number of times (or rows) to scroll Name : ScrRest (Screen Restore) Class : Display Level : Clone The ScrRest routine restores a display that was saved using ScrSave or a similar routine. It only works in text modes, and expects an 80x25 screen. See PutScreen or DPutScreen if you need to work with other screen sizes. ScrRest Array%(), Page%, Fast% Array%() array holding the display information Page% page on which to restore the display Fast% whether to use fast mode (0 no) Name : ScrSave (Screen Save) Class : Display Level : Clone The ScrSave routine saves the display to an integer array. Only text modes are supported. For an 80x25 display, the array must hold 4,000 bytes, so you would use DIM Array%(1 TO 2000). ScrSave expects an 80x25 screen. Use GetScreen or DGetScreen if you need to work with other screen sizes. ScrSave Array%(), Page%, Fast% Page% display page to get Fast% whether to use fast mode (0 no) ------- Array%() saved display information Name : SCrunch (Screen Crunch) Class : Display Level : Any This routine is designed to be used in conjunction with ScrSave and the other routines which store an entire 80x25 text screen in an array. It performs a "screen crunch", compressing the original data into a new array. The average result is about 8x smaller than the original screen, resulting in a vast savings in memory (4,000 bytes vs 500 or so). The compression algorithm is very fast and will not take any noticeable amount of time for most purposes. Besides saving main memory, this is great for storing screens as disk files! The compression will not only make the file(s) smaller, but will make disk access faster since there is less information to transfer. If you need to deal with text screen images of other than 80x25 in size, try the SCrunchSS routine instead. SCrunch DSeg%, DOfs%, CSeg%, COfs%, Bytes% DSeg% segment of the original screen image DOfs% offset of the original screen image CSeg% segment of array in which to store compressed image COfs% offset of array in which to store compressed image ------- Bytes% number of bytes in the compressed image Name : SCrunchSS (Screen Crunch, Sized Screen) Class : Display Level : Any This routine is designed to be used in conjunction with ScrSave and the other routines which store a text screen in an array. It performs a "screen crunch", compressing the original data into a new array. The average result is about 8x smaller than the original screen, resulting in a vast savings in memory. The compression algorithm is very fast and will not take any noticeable amount of time for most purposes. Besides saving main memory, this is great for storing screens as disk files! The compression will not only make the file(s) smaller, but will make disk access faster since there is less information to transfer. If you only work with 80x25 text screen images, you may find it more convenient to use the SCrunch routine instead. SCrunchSS DSeg%, DOfs%, Rows%, Cols%, CSeg%, COfs%, Bytes% DSeg% segment of the original screen image DOfs% offset of the original screen image Rows% rows in original screen image Cols% columns in original screen image CSeg% segment of array in which to store compressed image COfs% offset of array in which to store compressed image ------- Bytes% number of bytes in the compressed image Name : Sec2Time$ (Seconds to Time) Class : Time Level : Any This routine converts the number of seconds past midnight into a time string. TimeSt$ = Sec2Time$(Seconds&) Seconds& number of seconds past midnight ------- TimeSt$ time string (TIME$ format) Name : SetBit (Set Bit) Class : Numeric Level : Any This routine sets a single bit "on" in an integer. Bits are numbered 0-15, with 0 being the least significant bit. SetBit Number%, BitNr% Number% number for which to set bit BitNr% bit number (0-15) to set ------- Number% number with the specified bit set Name : SetCGAColor (Set CGA Color) Class : Display Level : Clone This routine allows you to set certain aspects of CGA colors which aren't available otherwise. It is very CGA-specific, however, and may not work on EGA or VGA systems. The color specified has different meanings in different CGA modes. In the SCREEN 1 graphics mode, it changes the background and border color. In SCREEN 2, however, it allows you to change the foreground color. While you are still stuck with a single foreground color, you can choose what that color will be. SetCGAColor Colour% Colour% color to set (see above) Name : SetComm (Set Comm port) Class : Serial Level : DOS Although QuickBASIC has a fair range of communications support, it doesn't do the capabilities of the PC full justice. It's also impossible to change the serial parameters "on the fly" without risking disconnection, if BASIC alone is used. SetComm gets around those limitations. It should be used -after- the appropriate comm port is OPENed by BASIC. Note that the true upper limits of the comm speed are determined by your program and by the hardware being used. Some PC/XTs may have trouble with 9,600 bps, for instance. The ability to set the serial port to a high speed doesn't guarantee that the hardware can handle it! SetComm CommPort%, Bps%, Parity%, WordLength%, StopBits% CommPort% serial port (1-4, though BASIC only uses 1-2) Bps% bits per second ("baud rate"): 0 for 300 5 for 9,600 1 for 600 6 for 19,200 2 for 1,200 7 for 38,400 3 for 2,400 8 for 57,600 4 for 4,800 9 for 115,200 Parity% parity: 0 none 1 odd 3 mark (always on) 2 even 4 space (always off) WordLength% word length (5-8) StopBits% stop bits (1-2; if WordLength=5, "2" means 1 1/2) Name : SetCommAddr (Set Comm Address) Class : Serial Level : Clone This routine allows you to set the base port address of a serial port. One use for SetCommAddr is to give QuickBASIC access to the comm port on those unusual machines which have a COM2 but no COM1. Use GetCommAddr to get the address of COM2, set the COM1 address accordingly, and tell QuickBASIC to use COM1. BASIC will normally handle COM1 and COM2, but not COM3 or COM4. Although there is no way to use more two ports at once, you can fool BASIC into using COM3 by swapping it with COM1, or COM4 by swapping it with COM2. Don't forget to set the ports back to their original values before your program ends! SetCommAddr PortNr%, PortAddr% PortNr% COM port number (1-4) PortAddr% port address Name : SetDateAT (Set Date of AT clock) Class : Time Level : BIOS (AT) This routine sets the date of the hardware real-time clock in AT-class computers. Depending on the DOS version, this date may be partially or completely independent of the date kept by DOS in software. DOS always reads the date from the hardware clock when it starts up. However, use of the DATE command in DOS (and the DATE$ function in QuickBASIC) may relate only to the software copy of the date, which is not always guaranteed to be the same as the date in the hardware clock due to certain discrepancies in DOS. You may express the year as either a two-digit or four-digit number. The ProBas and PBClone versions of this routine do not work the same way in regards to the year. ProBas assumed that any two-digit year was in the 1900s. In contrast, PBClone assumes that years 80-99 should be converted to 1980-1999 and that 0-79 should be converted to 2000-2079. I consider the PBClone method more appropriate, with the turn of the century moving closer. The date format used does not allow dates before 1980 anyway, so nothing is being lost by this change. SetDateAT MonthNr%, DayNr%, YearNr% MonthNr% month number (1-12) DayNr% day (1-31) YearNr% year (1980-2079; see above for two-digit years) Name : SetDrv (Set default Drive) Class : Disk Level : DOS This routine sets the default disk drive. If the specified drive does not exist, the current default drive will remain the default. SetDrv Drive$ Drive$ drive letter Name : SetError (Set Error code) Class : Miscellaneous Level : DOS The SetError routine allows you to set the "error level" to be returned by DOS when your program ends. This is particularly handy for returning information to batch files. Note that SetError is best used just before your program ENDs, to avoid complications. SetError ErrorLevel% ErrorLevel% exit code to be returned by your program Name : SetFAttr (Set File Attribute) Class : Disk Level : DOS This routine allows you to set the attribute of a file or subdirectory. Any combination of the following may be set: Normal 0 (nothing special) Read Only 1 file can be read, but not written to Hidden 2 file will be "invisible" System 4 (for special DOS files-- leave alone) Archive 32 (used by some backup utils- leave be) To set more than one attribute, just add the numbers for the desired attributes together. The attributes marked "leave alone" shouldn't be used casually, but if you're sure you know what you're doing... SetFAttr FileName$, FAttr% FileName$ name of the file (or subdirectory) to manipulate FAttr% attribute(s) to set Name : SetFTD (Set File Time and Date) Class : Disk Level : DOS This routine lets you set the time and date of a specified file. You may give the year either as two digits or four digits. The ProBas and PBClone versions of this routine do not work the same way in regards to the year. ProBas assumed that any two-digit year was in the 1900s. In contrast, PBClone assumes that years 80-99 should be converted to 1980-1999 and that 0-79 should be converted to 2000-2079. I consider the PBClone method more appropriate, with the turn of the century moving closer. The DOS date format does not allow dates before 1980 anyway, so nothing is being lost by this change. Note that the Second% value, if odd, will be rounded down to an even number. This is due to the way DOS compresses the time format, rather than any limitation in this routine. SetFTD File$, MonthNr%, DayNr%, YearNr%, HourNr%, _ MinuteNr%, SecondNr% File$ name of file for which to set the time and date MonthNr% month number (1-12) DayNr% day (1-31) YearNr% year (1980-2079; see above for two-digit years) HourNr% hour (0-23) MinuteNr% minute (0-59) SecondNr% second (0-59; if odd, rounded down to even number) ------- MonthNr% -1 if there was an error, else unchanged Name : SetKbd (Set Keyboard toggles) Class : Input Level : Clone The SetKbd routine allows you to set the state of any of the four keyboard toggles: Insert, Caps lock, Num lock, and Scroll Lock. You can give your input routines a professional touch by setting this toggles instead of making the user remember to do so. It's considered proper to restore the original keyboard toggles before your program exits, unless of course the purpose of the program is to leave the toggles in a particular state! The GetKbd routine can be used in conjunction with SetKbd to do this. SetKbd Insert%, Caps%, Num%, Scrl% Insert% whether to turn on "insert" mode (0 if no) Caps% whether to turn on "caps lock" (0 if no) Num% whether to put the keypad into numeric mode (0 no) Scrl% whether to turn on "scroll lock" (0 if no) Name : SetLabel (Set disk volume Label) Class : Disk Level : DOS This routine creates, renames or deletes a disk volume label. Note that a disk volume label is essentially a file name without an extension. It can contain any character that can normally be in a file name, plus spaces and periods. SetLabel Drive$, Label$, ErrCode% Drive$ drive to set label on (use "" for current drive) Label$ label to install (use "" to delete current label) ------- ErrCode% whether there was an error (0 no) Name : SetLogiDrive (Set Logical Drive) Class : Disk Level : DOS 3.2+ This routine is useful for systems which only have a single floppy drive. In such cases, DOS connects both drive letters A: and B: to the same drive. However, only one drive letter is active, and when you try to access the "other" drive, DOS displays the message: "Insert diskette for drive x: and press any key when ready." By setting the active drive yourself, you can bypass this message, and your program will look much more professional. SetLogiDrive Drive$, ErrCode% Drive$ drive letter to select (use "" for current drive) ------- ErrCode% whether there was an error (0 no) Name : SetMatI (Set Matrix to Integer) Class : Numeric Level : Any This routine sets as many elements of an integer array as you like, starting at a specified place in the array. A good use for it is to initialize an array (or a portion of it) to a given value. SetMatI DSeg%, DOfs%, Elements%, Value% DSeg% segment of the first array element to add DOfs% offset of the first array element to add Elements% number of array elements to which to add Value% value to which to set each array element Name : SetMatL (Set Matrix to Long) Class : Numeric Level : Any This routine sets as many elements of an long integer array as you like, starting at a specified place in the array. A good use for it is to initialize an array (or a portion of it) to a given value. SetMatL DSeg%, DOfs%, Elements%, Value& DSeg% segment of the first array element to add DOfs% offset of the first array element to add Elements% number of array elements to which to add Value& value to which to set each array element Name : SetMouseLoc (Set Mouse Location) Class : Mouse Level : BIOS This routine allows you to set the current location of the mouse cursor. It doesn't matter if the cursor is visible or invisible. SetMouseLoc is only for use in text mode. This routine will not work properly if there is no mouse available. Use the MMCheck routine if you are not sure. See also MMSetLoc, which is for use in graphics modes. SetMouseLoc Row%, Column% Row% mouse cursor row Column% mouse cursor column Name : SetPatch (Set Patch information) Class : Disk Level : DOS This routine is used after FindPatch. The FindPatch routine finds the first DATA statement to be patched. SetPatch places new information in that DATA statement and moves the file pointer to the position of the next DATA statement. Note that there must be only one item per DATA statement; this item must be a quoted string. The string in the DATA statement and the patch string must be the same length. If you need this routine to be able to handle variable-length strings, don't fret! Make the DATA string one character longer than the maximum you need, and use the extra character to indicate the actual string length: SetPatch CHR$(LEN(St$)) + St$ Then when you READ St$, decode it like so: St$ = MID$(St$, 2, ASC(St$)) Routines in this set include FindPatch, SetPatch, PatchDone. SetPatch St$ St$ string to patch into the current DATA statement Name : SetPrtAddr (Set Printer Address) Class : Printer Level : Clone This routine allows you to set the base port address of a parallel port. One use for this routine is to fool BASIC into using a different port than LPT1 for LPRINT. See also PRTSWAP. Note that PS/2 systems only have ports 1-3 available. They use the fourth port data area for holding other information. It may be a good idea to restrict yourself to ports 1-3 for compatibility purposes, although other computers allow ports 1-4. Don't forget to set the ports back to their original values before your program ends! SetPrtAddr PortNr%, PortAddr% PortNr% LPT port number (1-4 or 1-3 [see above]) PortAddr% port address Name : SetSub (Set default Subdirectory) Class : Disk Level : DOS Just like the DOS CD (or CHDIR) command, this routine allows you to change the current subdirectory. Unlike the corresponding DOS command, you may not use a period or double period as shorthand for a directory. However, you may specify either an absolute or relative path, as usual, and can also use either slashes or backslashes as delimiters. SetSub SubDir$, ErrCode% SubDir$ subdirectory name ------- ErrCode% error code: 0 if no error, else a DOS Error number Name : SetTimeAT (Set Time of AT clock) Class : Time Level : BIOS (AT) This routine sets the time to the hardware real-time clock in AT-class computers. Depending on the DOS version, this time may be partially or completely independent of the time kept by DOS in software. DOS always reads the time from the hardware clock when it starts up. However, use of the TIME command in DOS (and the TIME$ function in QuickBASIC) may relate only to the software copy of the time, which is not always guaranteed to be the same as the time in the hardware clock due to certain discrepancies in DOS. SetTimeAT HourNr%, MinuteNr%, SecondNr% HourNr% hour (0-23) MinuteNr% minute SecondNr% second Name : SetVerify (Set Verify state) Class : Disk Level : DOS The SetVerify routine allows you to set the state of the DOS VERIFY flag. When VERIFY is on, some checking is done to make sure that writing to the disk works as requested. The checks are not very good, however, and VERIFY slows down disk handling, so it is usually better to have VERIFY off. SetVerify VerifyOn% VerifyOn% whether to turn VERIFY on (0 if no) Name : SetVGAColor (Set VGA Color) Class : Display Level : BIOS This routine sets the color associated with a given color number. The color is specified as a combination of red, green, and blue intensities. Each intensity may range from off (0) to very bright (63). If you are dealing with more than one color at a time, you may find SetVGAPalette more appropriate. SetVGAColor ColorNr%, Red%, Green%, Blue% ColorNr% color number (1-16 or 1-255, depending on VGA mode) Red% red intensity (0-63) Green% green intensity (0-63) Blue% blue intensity (0-63) Name : SetVGAPalette (Set VGA Palette) Class : Display Level : BIOS This routine allows you to set any number of the VGA palette values from a TYPEd array. The TYPE for the array should be defined like this: TYPE Palet IRed AS STRING * 1 IBlue AS STRING * 1 IGreen AS STRING * 1 END TYPE This type holds a CHR$-encoded representation of the intensity of each component of the color. The values range from 0-63. You can change many palette settings at a time, very quickly, with this routine. This routine is sufficiently faster than the BASIC PALETTE statement as to make palette animation (and some stupendous special effects) possible. It may cause flickering on displays with less well-designed video BIOS chips, however. If you only need to set a few colors, you may find SetVGAColor more convenient. SetVGAPalette DSeg%, DOfs%, Start%, Colors% DSeg% segment of the palette array DOfs% offset of the palette array Start% color number to start with Colors% number of colors to set Name : SFRead (String File Read) Class : Disk / String Level : DOS This routine reads a string from a file that was opened by FOpen1 or FCreate. The length of the string you provide determines how many characters should be read. If it wasn't possible to read all the characters desired, an error code will be returned and the BytesRead% value will tell you how many characters were actually retrieved. St$ = SPACE$(BytesToRead%) SFRead Handle%, St$, BytesRead%, ErrCode% Handle% handle of the file from which to read ------- St$ data read from the file. Init to # of chars wanted BytesRead% number of bytes read from the file (if error) ErrCode% error code: 0 if no error, else DOS Error Name : SFWrite (String File Write) Class : Disk / String Level : DOS This routine writes a string to a file that was opened by FOpen1 or FCreate. The length of the string you provide determines how many characters will be written. If it wasn't possible to write the entire string to the file, an error code will be returned and the BytesWrit% value will tell you how many characters were actually written. SFWrite Handle%, St$, BytesWrit%, ErrCode% Handle% handle of the file to which to write St$ data to write to the file. ------- BytesWrit% number of bytes written to the file (if error) ErrCode% error code: 0 if no error, else DOS Error Name : ShiftL (Shift Left) Class : Numeric Level : Any This routine shifts the bits in an integer left by a desired amount. The effect of this is similar to multiplying the number by a power of two, if the number is positive, but is much faster. ShiftL Value%, Count% Value% number to shift left Count% bits by which to shift ------- Value% shifted number Name : ShiftLL (Shift Left Long) Class : Numeric Level : Any This routine shifts the bits in a long integer left by a desired amount. The effect of this is similar to multiplying the number by a power of two, if the number is positive, but is much faster. ShiftLL Value&, Count% Value& number to shift left Count% bits by which to shift ------- Value& shifted number Name : ShiftR (Shift Right) Class : Numeric Level : Any This routine shifts the bits in an integer right by a desired amount. The effect of this is similar to dividing the number by a power of two, if the number is positive, but is much faster. ShiftR Value%, Count% Value% number to shift right Count% bits by which to shift ------- Value% shifted number Name : ShiftRL (Shift Right Long) Class : Numeric Level : Any This routine shifts the bits in a long integer right by a desired amount. The effect of this is similar to dividing the number by a power of two, if the number is positive, but is much faster. ShiftRL Value&, Count% Value& number to shift right Count% bits by which to shift ------- Value& shifted number Name : ShlSt (Shift Left String of bits) Class : String Level : Any This routine shifts the bits in a string left by a desired amount. This may be helpful for manupulating strings containing bit flags, images, et al. ShlSt St$, Count% St$ string to shift left Count% bits by which to shift ------- St$ shifted string Name : ShowIcon (Show Icon) Class : Display File Level : BIOS This routine displays an icon file (MS Windows .ICO format) on the screen. The display mode may be any of the EGA or VGA graphics modes, and you can specify a starting X,Y coordinate. Only the standard icon format is supported. These icons are 32x32 pixels and are contained in 766-byte .ICO files. Note that colors are translated from Windows colors, which are a close (but not exact) match for BASIC colors. ShowIcon FileName$, X%, Y%, ErrCode% FileName$ name of icon file X% X coordinate (0-320 or 0-640 depending on mode) Y% Y coordinate (0-199, -349, etc; depends on mode) ------- ErrCode% error code (0 if none; >0, DOS error; <0, not .ICO) Name : ShrSt (Shift Right String of bits) Class : String Level : Any This routine shifts the bits in a string right by a desired amount. This may be helpful for manupulating strings containing bit flags, images, et al. ShrSt St$, Count% St$ string to shift right Count% bits by which to shift ------- St$ shifted string Name : SInput (String Input) Class : Input Level : Clone This is a flexible line input routine which supports WordStar and DOS-style editing, default entries, key screening, and any number of other options. To keep SInput manageable, the less volatile parameters are set with separate routines instead of being passed directly. The St$ parameter must be set to the maximum desired input length. It may also contain a default entry, in which case SLen% should be set to the length of the default entry (set SLen% to zero if there is no default entry). Character screening is done through selection of valid character types. This may be any combination of the following (add the desired types together): 1 letters 2 digits 4 symbols 16 graphics (ASCII 128-255) 32 spaces You can use -1 to allow any character. You can also make use of the NOT operator, e.g. NOT 2 allows everything but digits. The ExitCode% returns the key used to terminate input. This will normally be 13 (return) or 27 (esc), but other results may be returned depending on how you use the various SInputSet routines. Note that the cursor position is not altered when SInput exits, to avoid accidentally scrolling your screen. You are left with full control over the cursor. The SInput routine is designed with the idea of input forms and windows in mind. It is not capable of handling more than one line of text at a time. It also doesn't know how to wrap at the edge of the screen. Routines in this series include: SInput, SInputSet, SInputSet1, SInputSet2 Since everyone has their own ideas about the perfect input routine, I have recoded SInput largely in BASIC to allow registered PBClone owners to modify it easily. I've gotten a huge number of requests for SInput modifications in the past; hopefully this will be the best solution! SInput St$, SLen%, Valid%, MustFill%, VAttr%, ExitCode% St$ init to max length of input (may hold default) SLen% length of default entry (0 if none) Valid% valid character types (see above) MustFill% whether input field must be totally filled (0 no) VAttr% color/attribute for input (see CalcAttr) ------- St$ entered string SLen% length of entered string ExitCode% key used to exit (13 for <CR> or 27 for <ESC>) Name : SInputSet (String Input Settings) Class : Input Level : Clone This is one of a number of routines which allow you to modify the default operation of SInput. If you allow extended keys (like Alt keys and function keys) to exit SInput, the ExitCode% parameter will return the negative scan code of the key. Routines in this series include: SInput, SInputSet, SInputSet1, SInputSet2 SInputSet FillCh$, ExtExit%, BadBeep%, FullBeep%, Fast% FillCh$ character used to show field length (default "_") ExtExit% extended keys can be used to exit (default 0, no) BadBeep% beep on invalid keys (default 0, no) FullBeep% beep when input field is full (default 0, no) Fast% use fast display, may make CGA flicker (def 0, no) Name : SInputSet1 (String Input Settings) Class : Input Level : Clone This is one of a number of routines which allow you to modify the default operation of SInput. If you give SInput a default entry, it will normally place the cursor at the end of that entry when input begins. The CurPosn% option here allows you to place the cursor where you want it (1 - LEN(St$), or 0 for end of entry). Routines in this series include: SInput, SInputSet, SInputSet1, SInputSet2 SInputSet1 CurPosn%, FullExit% CurPosn% starting cursor posn within input field (default 0) FullExit% auto-exit when input field is full (default 0, no) Name : SInputSet2 (String Input Settings) Class : Input Level : Clone This is one of a number of routines which allow you to modify the default operation of SInput. If you allow tabs to exit SInput, the ExitCode% may return an additional value: 9 (tab). A "back tab", by the way, can be retrieved if you use SInputSet to allow extended keys to exit (back tab would return -15). Routines in this series include: SInput, SInputSet, SInputSet1, SInputSet2 SInputSet2 Capitalize%, TabExit% Capitalize% whether to capitalize letters (default 0, no) TabExit% whether tab key can to exit (default 0, no) Name : SortD (Sort Double precision) Class : Array management Level : Any This routine sorts the elements in an array of double-precision numbers. The array is assumed to start at element 1. You may specify the last element in the array, allowing you to sort only part of an array if you like. If you would like the results to be largest-to-smallest, rather than smallest-to-largest, just call ReverseD after this routine. SortD Array#(), Elements% Array#() array to be sorted Elements% number of elements in array ------- Array#() sorted array Name : SortI (Sort Integer) Class : Array management Level : Any This routine sorts the elements in an array of integers. The array is assumed to start at element 1. You may specify the last element in the array, allowing you to sort only part of an array if you like. If you would like the results to be largest-to-smallest, rather than smallest-to-largest, just call ReverseI after this routine. SortI Array%(), Elements% Array%() array to be sorted Elements% number of elements in array ------- Array%() sorted array Name : SortL (Sort Long integer) Class : Array management Level : Any This routine sorts the elements in an array of long integers. The array is assumed to start at element 1. You may specify the last element in the array, allowing you to sort only part of an array if you like. If you would like the results to be largest-to-smallest, rather than smallest-to-largest, just call ReverseL after this routine. SortL Array&(), Elements% Array&() array to be sorted Elements% number of elements in array ------- Array&() sorted array Name : SortS (Sort Single precision) Class : Array management Level : Any This routine sorts the elements in an array of single-precision numbers. The array is assumed to start at element 1. You may specify the last element in the array, allowing you to sort only part of an array if you like. If you would like the results to be largest-to-smallest, rather than smallest-to-largest, just call ReverseS after this routine. SortS Array!(), Elements% Array!() array to be sorted Elements% number of elements in array ------- Array!() sorted array Name : SortSt (Sort String) Class : Array management Level : Any This routine sorts the elements in a string array. The array is assumed to start at element 1. You may specify the last element in the array, allowing you to sort only part of an array if you like. You can also specify whether the capitalization of letters in a string should matter for sorting purposes. If you would like the results to be last-to-first, rather than first-to-last, just call ReverseSt after this routine. SortSt Array$(), Elements%, CapsCount% Array$() array to be sorted CapsCount% use 0 if uppercase/lowercase doesn't matter Elements% number of elements in array ------- Array$() sorted array Name : Soundex (Soundex code) Class : String Level : Any This is a string comparison routine which returns a code that is loosely based on the "sound" of a word. It removes the vowels and repeated characters from a word, then converts it into a numeric code. Any words with the same code are considered to sound alike. While not perfect, this algorithm does a fast and reasonably good job. It can be helpful in applications like spelling checkers and phone books, where a search based on exact text may not be appropriate. Code$ = St$ Soundex St$, Code$, CodeLen% Code$ = LEFT$(St$, CodeLen%) St$ string to be encoded ------- Code$ result code. Init to >= length of original string. CodeLen% length of the result code Name : SpeedKey (Speed up Keyboard) Class : Input Level : BIOS (AT) This routine provides control over the keyboard repeat rate for AT-class machines. Increasing the repeat rate can make the computer seem a lot more responsive and pleasant to deal with. RepDelay% Delay Time 0 250 milliseconds 1 500 ms 2 750 ms 3 1 second RepRate% is the key repeat rate, 0-31 (from around 30 cps to around 2 cps) SpeedKey RepDelay%, RepRate% RepDelay% delay before starting to repeat (0-3, default 1) RepRate% rate at which to repeat key (0-31, default 11) Name : Split (Split screen image) Class : Display Level : Clone This provides an elegant way to clear a text-mode screen. It splits the display into four parts, scrolling each part up or down until it slides off the screen. Split Name : Spooler (check for print Spooler) Class : Printer Level : DOS The Spooler routine allows you to see whether the print spooler (installed by the DOS PRINT utility) is available. Spooler Status% ------- Status% spooler status: -1 it's installed 0 it isn't installed, but can be 1 it isn't installed, and can't be Name : SSrch (String Search) Class : String Level : Any This is a string search routine which tells you whether one string can be found inside another. Uppercase/lowercase distinctions are ignored. Leading and trailing spaces in the string for which to search are also ignored. Note that the positions of the main string and search string parameters are in the reverse of the order you might expect. SSrch Search$, MainSt$, Found% Search$ string for which to search MainSt$ string to be searched ------- Found% whether a match was found (0 if no) Name : StrDel (String Delete) Class : String Level : Any StrDel deletes a character from a string. Actually, it doesn't make the string any shorter, but it acts like a delete. The end of the string is filled with a space. StrDel St$, Posn% St$ string from which to delete a character Posn% position of the character to delete (1-LEN(St$)) ------- St$ processed string Name : StrIns (String Insert) Class : String Level : Any StrIns inserts a space into a string. Actually, it doesn't make the string any longer, but it acts like an insert. The former end of the string is discarded. StrIns St$, Posn% St$ string in which to insert a space Posn% where to insert the space (1-LEN(St$)) ------- St$ processed string Name : Strip (Strip spaces) Class : String Level : Any This routine strips both leading and trailing white space from a string. This includes control characters as well as blanks (anything below CHR$(33)). Strip St$ St$ string to process ------- St$ processed string Name : Strip2$ (Strip Spaces) Class : String Level : Any This routine strips both leading and trailing white space from a string. It works just like Strip, but is a function rather than a subprogram. White space includes control characters as well as blanks (anything below CHR$(33)). Result$ = Strip2$(St$) St$ string to process ------- Result$ processed string Name : StripBlanks (Strip Blanks) Class : String Level : Any This routine strips leading and/or trailing white space from a string. This includes control characters as well as blanks (anything below CHR$(33)). See also StripSpaces. StripBlanks St$, Which%, StLen% St$ = LEFT$(St$, StLen%) St$ string to process Which% 1: strip left, 2: strip right, 3: strip left and right ------- St$ processed string StLen length of processed string Name : StripChar (Strip Characters) Class : String Level : Any This routine strips all occurrences of a given list of characters out of a string. Among the uses for this are cleaning up user-entered values. For instance, a strip list of "$," would remove commas and dollar signs from a number, and "()- " will remove telephone delimiters. StripChar St$, StripList$, StLen% St$ = LEFT$(St$, StLen%) St$ string to process StripList$ characters to remove from the string ------- St$ processed string StLen% length of processed string Name : StripRange (Strip Range of characters) Class : String Level : Any This routine strips an inclusive range of characters out of a string. The range is specified as the first and last ASCII codes to strip. For instance, using a low character of "0" and a high of "9" would remove all digits from a string. StripRange St$, ASC(LowChar$), ASC(HighChar$), StLen% St$ = LEFT$(St$, StLen%) St$ string to process LowChar$ lowest character to strip HighChar$ highest character to strip ------- St$ processed string StLen% length of processed string Name : StripSpaces (Strip Spaces) Class : String Level : Any This routine strips leading and/or trailing spaces from a string. See also StripBlanks. StripSpaces St$, Which%, StLen% St$ = LEFT$(St$, StLen%) St$ string to process Which% 1: strip left, 2: strip right, 3: strip left and right ------- St$ processed string StLen% length of processed string Name : StrSqu$ (String Squish) Class : String Level : Any This is a text compression routine which uses 2-gram and 3-gram compression to shrink a string. It combines the best of the StrSqu2 and StrSqu3 routines with additional ease of use. The one limitation is that only plain text may be compressed; the text may not contain CHR$(128) through CHR$(255), as these codes are used by the compression algorithm. The compressed text can be restored to original form with the StrUnsq$ function. Result$ = StrSqu$(St$) St$ string to compress ------- Result$ compressed string Name : StrSqu2 (String Squish, 2-gram) Class : String Level : Any This is a text compression routine which uses a 2-gram algorithm to compress common pairs of characters out of a string. You can reasonably expect to reduce the text size by about a third with this routine. Compression is quite fast. The one limitation is that only plain text may be compressed; the text may not contain CHR$(128) through CHR$(255), as these codes are used by the compression algorithm. You must use StrSquLen2 before this routine to determine the proper length to which to initialize the result string. The compressed text can be restored to original form with StrUnsqu2. StrSquLen2 St$, ResultLen% Result$ = SPACE$(ResultLen%) StrSqu2 St$, Result$ St$ string to compress ------- Result$ compressed string Name : StrSqu3 (String Squish, 3-gram) Class : String Level : Any This is a text compression routine which uses a 3-gram algorithm to compress common triplets of characters out of a string. You can reasonably expect to reduce the text size by about a third with this routine. Compression is quite fast. The one limitation is that only plain text may be compressed; the text may not contain CHR$(128) through CHR$(255), as these codes are used by the compression algorithm. You must use StrSquLen3 before this routine to determine the proper length to which to initialize the result string. The compressed text can be restored to original form with StrUnsqu3. StrSquLen3 St$, ResultLen% Result$ = SPACE$(ResultLen%) StrSqu3 St$, Result$ St$ string to compress ------- Result$ compressed string Name : StrSquLen2 (String Squished Length, 2-gram) Class : String Level : Any This routine is used in conjunction with the StrSqu2 text compressor. It tells you what size the resulting text will be. See StrSqu2 for further information. StrSquLen2 St$, ResultLen% Result$ = SPACE$(ResultLen%) StrSqu2 St$, Result$ St$ string to compress ------- ResultLen% length of the compressed string Name : StrSquLen3 (String Squished Length, 3-gram) Class : String Level : Any This routine is used in conjunction with the StrSqu3 text compressor. It tells you what size the resulting text will be. See StrSqu3 for further information. StrSquLen3 St$, ResultLen% Result$ = SPACE$(ResultLen%) StrSqu3 St$, Result$ St$ string to compress ------- ResultLen% length of the compressed string Name : StrUnsq$ (String Unsquish) Class : String Level : Any This routine decompresses text which was compressed by the StrSqu$ function. Result$ = StrUnsq$(St$) St$ string to decompress ------- Result$ decompressed string Name : StrUnsqu2 (String Unsquish, 2-gram) Class : String Level : Any This routine decompresses text which was compressed by StrSqu2. Text is decompressed at lightning speed, as this routine has no overhead to speak of. You must use StrUnsquLen2 before this routine to determine the proper length to which to initialize the result string. StrUnsquLen2 St$, ResultLen% Result$ = SPACE$(ResultLen%) StrUnsqu2 St$, Result$ St$ string to decompress ------- Result$ decompressed string Name : StrUnsqu3 (String Unsquish, 3-gram) Class : String Level : Any This routine decompresses text which was compressed by StrSqu3. Text is decompressed at lightning speed, as this routine has no overhead to speak of. You must use StrUnsquLen3 before this routine to determine the proper length to which to initialize the result string. StrUnsquLen3 St$, ResultLen% Result$ = SPACE$(ResultLen%) StrUnsqu3 St$, Result$ St$ string to decompress ------- Result$ decompressed string Name : StrUnsquLen2 (String Unsquished Length, 2-gram) Class : String Level : Any This routine is used in conjunction with the StrUnsqu2 text decompressor. It tells you what size the resulting text will be. See StrUnsqu2 for further information. StrUnsquLen2 St$, ResultLen% Result$ = SPACE$(ResultLen%) StrUnsqu2 St$, Result$ St$ string to decompress ------- ResultLen% length of the decompressed string Name : StrUnsquLen3 (String Unsquished Length, 3-gram) Class : String Level : Any This routine is used in conjunction with the StrUnsqu3 text decompressor. It tells you what size the resulting text will be. See StrUnsqu3 for further information. StrUnsquLen3 St$, ResultLen% Result$ = SPACE$(ResultLen%) StrUnsqu3 St$, Result$ St$ string to decompress ------- ResultLen% length of the decompressed string Name : SubExist (Subdirectory Existence) Class : Disk Level : DOS This routine lets you see if a given drive and/or subdirectory actually exists. See also SubExist2, the FUNCTION version of this routine. SubExist SubDir$, Found% SubDir$ name of the path to check ------- Found% whether the path exists (0 if no, -1 if yes) Name : SubExist2% (Subdirectory Existence) Class : Disk Level : DOS This routine lets you see if a given drive and/or subdirectory actually exists. See also SubExist, the SUB version of this routine. Found% = SubExist2%(SubDir$) SubDir$ name of the path to check ------- Found% whether the path exists (0 if no, -1 if yes) Name : Time2Int (Time to Integer) Class : Time Level : Any This routine compresses a time into a single integer. Note that this integer is not in a format that lends itself to simple computation-- you cannot subtract one from another to find out the length of time between them. If that's what you want, try the Elapsed routine. Note that odd numbers of seconds will be rounded down to the previous even number. This is a result of the storage format used. Time2Int HourNr%, MinuteNr%, SecondNr%, IntTimeNr% HourNr% hour (0-23) MinuteNr% minute SecondNr% second ------- IntTime% time compressed into an integer Name : Time2Sec& (Time to Seconds) Class : Time Level : Any This routine converts a time string into the number of seconds past midnight. This is convenient if you want to find the difference between two times or to calculate what time it will be after a given interval. Seconds& = Time2Sec&(TimeSt$) TimeSt$ time string (TIME$ format) ------- Seconds& number of seconds past midnight Name : TimeN2S (Time Numbers to String) Class : Time Level : Any / DOS Many of the PBClone routines return the time as a set of numbers. This routine provides an easy way to convert those numbers into string form. The time format used (whether seconds are included) will be based on the length of the string which you pass to the routine. For instance, a string like "xx:xx" would return a time like "21:35", whereas "xx:xx:xx" would return "21:35:08". TimeSt$ = "xx:xx:xx" TimeN2S HourNr%, MinuteNr%, SecondNr%, TimeSt$ HourNr% hour (0-23) MinuteNr% minute SecondNr% second ------- TimeSt$ time string. Init to 5 or 8 characters (see above). Name : TimeS2N (Time String to Numbers) Class : Time Level : Any Many of the PBClone routines need to be passed the time as a set of numbers. This routine provides an easy way to convert a time from string form into numbers. You may use either "xx:xx:xx" or "xx:xx" form to specify the time (the string length is important, but the delimiter and contents of the string are ignored). If the 5-character short form is used, the Second% value will be zero. TimeS2N HourNr%, MinuteNr%, SecondNr%, TimeSt$ TimeSt$ time string. Init to 5 or 8 characters (see above). ------- HourNr% hour (0-23) MinuteNr% minute SecondNr% second (0 if 5-char format) Name : TInstr (Typed INSTR) Class : String Level : Any As you might guess from the "Instr" part of the name, this routine searches a string. Instead of searching for a specific character or substring, though, it looks for a specific type of character-- letters, numbers, control codes, or whatever. You can search for the first of a combination of types, too, which also allows searching for "anything but" a specific type. The character type code is specified by adding any of the following: 1 alphabetic 2 numeric 4 symbolic 8 control 16 graphics 32 space The TInstr routine is handy for parsing and cleaning up user input, among other uses. TInstr St$, ChrType%, Place% St$ string to search ChrType% type of character(s) to search for ------- Place% position of first char of desired type, or 0 Name : ToPostal$ (To Postal Abbreviation) Class : String Level : Any This function returns the two-letter U.S. postal abbreviation corresponding to a given place name. It handles all valid abbreviations, including states (e.g., "AZ" = "Arizona") and a number of other countries (e.g., "PR" = "Puerto Rico"). A null string ("") is returned if the specified place can't be abbreviated. Capitalization is not important, but spelling is. This function is best used with validated input. If you have control of the input method, consider using a "pick list" menu. Otherwise, a fuzzy scanner would be appropriate, using perhaps the Bickel and/or Soundex routines to find the closest match if a perfect match is not found. The conversion can also be done the other way around-- see the FromPostal$ function. Abbrev$ = ToPostal$(PlaceName$) PlaceName$ place name to abbreviate ------- Abbrev$ two-letter postal abbreviation Name : TVIdle (TopView Idle) Class : Miscellaneous Level : BIOS If your program is running under TopView or a compatible multitasker, such as DESQview, it can take advantage of this routine to give up the rest of its time slice. This would normally done at a point where the program is liable to be idle for a brief while, such as during user input. The advantage of giving up part of your program's time when you can afford it is that any other running programs will be able to make use of it, hence improving overall system performance. TVIdle Name : TypeIn (Type In) Class : Input Level : Clone This is an unusual routine which combines both output and input. It sends a string to the keyboard buffer, where it acts as if it had been typed in by someone. The string may be up to 15 key codes in length (anything past 15 keys will be ignored, due to the limited length of the keyboard buffer). Normal keys can be put into the string simply as characters. Extended keys, like Alt-key combinations, arrow keys, and function keys, must be encoded as CHR$(0) + CHR$(ScanCode), where the ScanCode is the key's scan code. You can look up such scan codes in your BASIC manual or use GetKey to find out what they are. Extended keys, although apparently taking up two characters, only take up one space in the keyboard buffer. The TypeIn routine allows for this fact. Among other things, this routine can be used to provide default answers to input routines, or to execute another program once your program exits. TypeIn St$ St$ keys to be "typed" into the keyboard buffer Name : TypePrint (Type Print) Class : Display Level : Clone TypePrint displays a string as if it was being typed. The string is displayed a character at a time, with a delay between each character. You may choose one color to highlight the just-displayed character and another color for the character to turn after the delay is done. TypePrint St$, Row%, Column%, WaitTime%, TmpAttr%, _ VAttr%, Fast% St$ string to display Row% row at which to display string Column% column at which to display string WaitTime% delay between chars (milliseconds; 20-60 is decent) TmpAttr% color/attribute for just-displayed character VAttr% color/attribute for character after the delay is up Fast% whether to use fast displays (0 no) Name : UnCalcAttr (Undo Calculated Attribute) Class : Display Level : Any Many of the display routines in this library require an "attribute" rather than foreground and background colors. An attribute is a combination of the foreground and background colors in a format which is used by all types of displays when in text mode. The UnCalcAttr routine allows you to decode the original colors given the attribute. Foreground colors are usually specified as 0-31, with backgrounds as 0-7. If you turn blinking off (see Blink), it may be more convenient to express the same thing as foreground 0-15, background 0-15. The CalcAttr routine will accept either way of expressing it. Note, however, that UnCalcAttr will always return the former pair of results, since it has no way of knowing whether Blink has been used (foreground 0-31, background 0-15). The below routine shows how to get around this, if needed. UnCalcAttr Foreground%, Background%, VAttr% ' the following is optional and may not be desired... ' it converts colors to "no blink" equivalents (see above) IF Foreground% AND 16 THEN Foreground% = Foreground% - 16 Background% = Background% + 8 END IF VAttr% color "attribute" ------- Foreground% foreground color Background% background color Name : UnSCrunch (Undo Screen Crunch) Class : Display Level : Any This routine is designed to be used in conjunction with ScrRest and the other routines which restore an entire 80x25 text screen from an array. It expands screens that were compressed by SCrunch to their full original size. The uncompression algorithm is very fast and will not take any noticeable amount of time for most purposes. If your original screen was not 80x25 in size, use the UnSCrunchSS routine instead. REDIM FullScreen%(1 TO 2000) DSeg% = VARSEG(FullScreen%(1)) DOfs% = VARPTR(FullScreen%(1)) UnSCrunch DSeg%, DOfs%, CSeg%, COfs% DSeg% segment of array in which to store expanded image DOfs% offset of array in which to store expanded image CSeg% segment of the compressed image COfs% offset of the compressed image Name : UnSCrunchSS (Undo Screen Crunch Sized Screen) Class : Display Level : Any This routine is designed to be used in conjunction with ScrRest and the other routines which restore a text screen from an array. It expands screens that were compressed by SCrunchSS or SCrunch to their full original size. The uncompression algorithm is very fast and will not take any noticeable amount of time for most purposes. If your original screen was 80x25 in size, you may find it convenient to use the UnSCrunch routine instead. REDIM FullScreen%(1 TO Rows% * Cols%) DSeg% = VARSEG(FullScreen%(1)) DOfs% = VARPTR(FullScreen%(1)) UnSCrunchSS DSeg%, DOfs%, Rows%, Cols%, CSeg%, COfs% DSeg% segment of array in which to store expanded image DOfs% offset of array in which to store expanded image Rows% rows in image Cols% columns in image CSeg% segment of the compressed image COfs% offset of the compressed image Name : UnSplit (Undo Split) Class : Display Level : Clone This routine does the opposite of Split-- instead of clearing the screen by scrolling it in different directions, it puts text on the screen by scrolling it on from different locations. The effect is quite stunning. The information to place on the screen comes from an array that you specify which contains a saved screen. Only 80x25 text modes are supported. Any of the screen save routines (e.g., ScrSave) may be used to load the array. In a typical case, you will use this routine with screens that were created in advance and stored to disk for use by your program. UnSplit Scrn%(), Fast% Scrn%() array containing the text to display Fast% whether to use fast mode (0 no) Name : Upcase (Uppercase) Class : String Level : Any This routine, like BASIC's UCASE$ function, converts a string to uppercase. Since it doesn't have to create a new return string (a fairly slow process), it's faster than the BASIC equivalent. The Upcase routine is designed for the U.S. character set. If your program is intended for distribution, you would be well advised to use Upcase1 instead, as it supports international character sets. Upcase St$ St$ string to be capitalized ------- St$ capitalized string Name : Upcase1 (Uppercase) Class : String Level : DOS This routine, like BASIC's UCASE$ function, converts a string to uppercase. It converts letters in the extended character set as well as the usual letters, making it well suited for text which may not be in English. Note that DOS 5.0 is required for optimal performance. With older DOS versions, this routine makes assumptions about the character set which may not be appropriate. Upcase1 St$ St$ string to be capitalized ------- St$ capitalized string Name : UpcaseI% (Uppercase Integer char) Class : Numeric Level : Any This function converts a character to uppercase. Rather than taking a string parameter, though, UpcaseI% works on an integer which contains an ASCII code. The UpcaseI% function is designed for the U.S. character set. If your program is intended for distribution, you would be well advised to use UpcaseI1% instead, as it supports international character sets. CapCh% = UpcaseI%(Ch%) Ch% character to be capitalized ------- CapCh% capitalized character Name : UpcaseI1% (Uppercase Integer char) Class : Numeric Level : DOS This function converts a character to uppercase. Rather than taking a string parameter, though, UpcaseI% works on an integer which contains an ASCII code. Note that DOS 5.0 is required for optimal performance. With older DOS versions, this routine makes assumptions about the character set which may not be appropriate. CapCh% = UpcaseI1%(Ch%) Ch% character to be capitalized ------- CapCh% capitalized character Name : UpdTVScreen (Update TopView Screen) Class : Display Level : BIOS UpdTVScreen tells a TopView-compatible multitasker to update the screen using a specified screen buffer (use GetTVScreen to get the buffer location). Some multitaskers will do this automatically, but some won't. It's safe to use this routine either way. See also GetDView, GetTView, GetTVScreen. UpdTVScreen DSeg%, DOfs% DSeg% segment of screen buffer DOfs% offset of screen buffer Name : VGARest13 (VGA Restore for SCREEN 13) Class : Display Level : Clone This routine allows you to restore a SCREEN 13 (VGA, 320x200, 256 color) display that was saved using VGASave13 (see). VGARest13 DSeg%, DOfs% DSeg% segment of storage array, returned by VARSEG DOfs% offset of storage array, returned by VARPTR Name : VGASave13 (VGA Save of SCREEN 13) Class : Display Level : Clone This routine allows you to save a SCREEN 13 (VGA, 320x200, 256 color) display that can be restored using VGARest13 (see). The array used to hold the screen must contain 64,000 bytes. For an integer array, this means that you must create the array by DIM Array%(1 TO 32000). VGASave13 DSeg%, DOfs% DSeg% segment of storage array, returned by VARSEG DOfs% offset of storage array, returned by VARPTR Name : WeekDay0 (Week Day) Class : Time Level : DOS This routine tells you what the day of the week is, just the thing for calendar programs and whatnot. The day is returned as a number from 1-7, which identifies a day from Sunday through Saturday. WeekDay0 DayNr% ------- DayNr% current day Name : WeekDay1 (Week Day) Class : Time Level : Any This routine tells you the day of the week for any given date. WeekDay1 MonthNr%, DayNr%, YearNr%, DayName$ MonthNr% month number (1-12) DayNr% day number (1-31) YearNr% year number (1900 on) ------- DayName$ day of the week Name : WinCheck (Windows Check) Class : Equipment Level : BIOS The WinCheck routine tells you what version of Microsoft Windows is in use, if any. It returns the results as two integers containing the major and minor version numbers. For instance, Windows 3.0 would return a major number of 3, minor 0. Windows/386 v2.x will be identified as 2.0. If Windows is not running, 0.0 will be returned. NOTE that this routine is not able to detect Windows 1.x versions! WinCheck MajorV%, MinorV% ------- MajorV% major part of the Windows version MinorV% minor part of the Windows version Name : WindowMan2 (Window Manager) Class : Display Level : Clone This routine is identical to WindowManager but for the fact that it allows you to design your own custom window frames. Please see the description of WindowManager for general information. These are the additional frame types: 6 custom frame composed of a single character 7 custom frame composed of the specified 7-character list: top left corner, top middle, top right corner, left middle, right middle, bottom left corner, bottom middle, bottom right corner /------------------------------------------------------------\ | A custom frame like this would be defined as frame type 7, | | with a frame string of "/-\||\-/", for instance. | \------------------------------------------------------------/ ************************************************* * On the other hand, a frame like this would be * * frame type 6, with a frame string of "*". * ************************************************* Note that this routine differs from the ProBas equivalent in that it supports full frame definitions through frame type 7 (ProBas only supports type 6). The other differences mentioned under WindowManager are also relevant. WindowMan2 TRow%, LCol%, BRow%, RCol%, Frame%, FSt$, Fore%, Back%, Grow%, Shade%, TFore%, Title$, Page%, Fast% TRow% top row of window LCol% left column of window BRow% bottom row of window RCol% right column of window Frame% frame type (see above) FSt$ frame definition string (see above) Fore% frame foreground color Back% frame background color Grow% window growing option (see above) Shade% window shadow option (see above) TFore% title foreground color Title$ window title ("" if none) Page% display page (normally zero) Fast% whether to use fast mode (0 no) Name : WindowMan3 (Window Manager) Class : Display Level : Clone This routine is identical in function to WindowManager. The parameters are mostly passed as an array, however, instead of one by one. Please see the description of WindowManager for general information. WindowMan3 Parm%(), Title$ Parm%(1) top row of window Parm%(2) left column of window Parm%(3) bottom row of window Parm%(4) right column of window Parm%(5) frame type (see above) Parm%(6) frame foreground color Parm%(7) frame background color Parm%(8) window growing option (see above) Parm%(9) window shadow option (see above) Parm%(10) title foreground color Parm%(11) display page (normally zero) Parm%(12) whether to use fast mode (0 no) Title$ window title ("" if none) Name : WindowMan4 (Window Manager) Class : Display Level : Clone This is an extremely cut-down version of WindowManager, providing no more than a simple frame generator. These are the available frame types: 0 no frame 1 single lines 2 double lines 3 single horizontal, double vertical lines 4 double horizontal, single vertical lines 5 block graphic lines Note that this routine is different from its ProBas equivalent in that a new frame type (5) is available. WindowMan4 TRow%, LCol%, BRow%, RCol%, Frame%, VAttr%, _ Page%, Fast% TRow% top row of window LCol% left column of window BRow% bottom row of window RCol% right column of window Frame% frame type (see above) VAttr% frame color/attribute (use CalcAttr) Page% display page (normally zero) Fast% whether to use fast mode (0 if no, to avoid snow on CGAs) Name : WindowManager (Window Manager) Class : Display Level : Clone WindowManager displays a pop-up window according to your specifications. The window may have any of a variety of frames, a title, or a shadow, and it may appear instantly or "grow" onto the screen. Only text mode is supported. These are the available frame types: 0 no frame 1 single lines 2 double lines 3 single horizontal, double vertical lines 4 double horizontal, single vertical lines 5 block graphic lines These are the available shadows: -3 transparent shadow on the right -2 transparent shadow on the left -1 solid black shadow on the left 0 no shadow 1+ shadow attribute (use CalcAttr) for a colored shadow Options for growing windows are as follows: -1 grow as fast as possible 0 pop onto the screen 1+ grow with delay given in milliseconds (15 works for me) Note that this routine is different from its ProBas equivalent in a number of respects. The grow delay time is different. Growing is done more smoothly. The shadow and title parameters are not changed by this routine. A new frame type (5) was added. If a title is too long, it is truncated instead of being ignored completely. Using a -1 as the title foreground color will not turn off the title; instead, use a null title string. WindowManager TRow%, LCol%, BRow%, RCol%, Frame%, Fore%, Back%, Grow%, Shade%, TFore%, Title$, Page%, Fast% TRow% top row of window LCol% left column of window BRow% bottom row of window RCol% right column of window Frame% frame type (see above) Fore% frame foreground color Back% frame background color Grow% window growing option (see above) Shade% window shadow option (see above) TFore% title foreground color Title$ window title ("" if none) Page% display page (normally zero) Fast% whether to use fast mode (0 no) Name : WriteBitF (Write Bit Field) Class : Numeric Level : Any This routine allows you to set an element of a virtual array. The actual array can be any numeric type, as it is just being used as a storage area. The virtual array is composed of numbers of a bit length that you specify (1-8). This provides efficient storage for numbers which have a limited range. Here's how you DIM the actual array, assuming an integer array is used: DIM Array%(1 TO (VirtElements * VirtBits + 15) \ 16) "VirtElements" is the number of elements in the virtual array and "VirtBits" is the number of bits per element. See also ReadBitF. WriteBitF DSeg%, DOfs%, ElementNr&, BitLen%, Value% DSeg% segment of actual array DOfs% offset of actual array ElementNr& virtual element number (starts at 0) BitLen% bits per virtual element (1-8) Value% value to set element to (range depends on BitLen%) Name : Xlate (Translate) Class : String Level : Any The Xlate routine allows for translating a string, character by character, very quickly. It uses a translation table that you provide. This table is 256 bytes long, one byte for each character in the ASCII table. The translation is done by position-- for instance, if the original character was "A" (ASCII 65), the translated character will be whatever is in the translation table at position 66. Why 66, when "A" is 65? Because ASCII runs from 0-255, but the translation string is 1-256: everything is one higher in the string than the ASCII character it represents. Translation capabilities are handy in communications software. They can also be used in other things. One simple use would be to set up a translation table where all lowercase characters would be converted to uppercase. You might ask why, since BASIC has a UCASE$ function and PBClone has an Upcase routine. Well, Upcase is faster than UCASE$, since it doesn't have to create a return string; but Xlate would be even faster, since it translates every character directly instead of deciding whether it's a lowercase letter! Simple encoding, WordStar file decryption, string reversal, uppercase / lowercase conversion, and many other things can be done with Xlate. Remember to initialize all 256 characters in the translation table! Xlate St$, XlateTable$ St$ string to translate XlateTable$ translation table ------- St$ translated string Name : XMPrint (Translate and MS-DOS Print) Class : Display Level : DOS A combination of the Xlate and DMPrint routines, this 'un allows you to display using DOS services while being able to translate or screen out characters. Each character of the string to display is passed through a translation table you provide (256 bytes, where each position corresponds directly to the ASCII code of the same number [0-255]). If the result is 0, the character is not displayed. Otherwise, the translated character is displayed using DOS display services. The new cursor position is returned so you can inform BASIC about it. Note that the new cursor position may not be accurate! Some ANSI drivers do not update the BIOS cursor position info, in which case the results won't be useful. That's a hazard of using DOS output. XMPrint St$, XlateTable$, Row%, Column% LOCATE Row%, Column% St$ string to display XlateTable$ translation table ------- Row% current row Column% current column Name : XorSt (XOR String) Class : String Level : Any This routine XORs each byte in one string with the corresponding byte in a second string. The strings must be the same length. XorSt St1$, St2$ St1$ string to XOR St2$ string to XOR with ------- St1$ result Name : XQPrint (Extended Quick Print) Class : Display Level : Clone This routine provides a rather crude, but very fast, display capability. It works like the PRINT statement in BASIC, except that it doesn't move the cursor or process control codes. It works only in text modes. See also QPrint, a slightly less flexible (but even faster) routine. XQPrint St$, Row%, Column%, VAttr%, Page%, Fast% St$ string to display Row% starting row Column% starting column VAttr% color/attribute (see CalcAttr) Page% display page (unused on MDA/Herc; normally 0) Fast% whether to use fast mode (0 no) Name : XQPrintOver (Extended Quick Print Overwrite) Class : Display Level : Clone This routine provides a rather crude, but very fast, display capability. It works like the PRINT statement in BASIC, except that it doesn't move the cursor or process control codes. It works only in text modes. This is a slightly unusual variant on a print routine. It displays all characters except spaces. If your string contains a space, that position on the screen will be skipped. In other words, it acts kind of like an overlay. This can be handy when you have text in alternating colors. I came up with this routine when I designed a program with a function key display at the bottom of the screen-- the names of the function keys were one color and the associated definitions were another color. It was obvious that the easiest way of handling that would be to use an "overlay" approach. The function key definitions were laid down with XQPrint. I then overlaid the line with the function key names in a different color, using XQPrintOver. If you need a "solid" space, rather than a "transparent" space, use CHR$(255) instead of CHR$(32). XQPrintOver St$, Row%, Column%, VAttr%, Page%, Fast% St$ string to display Row% starting row Column% starting column VAttr% color/attribute (see CalcAttr) Page% display page (unused on MDA/Herc; normally 0) Fast% whether to use fast mode (0 no)